# OpenCode Go / Zen 官方 API 实测结论

> 用真实 key 实测结论。官方接口可能调整，以实测为准。

## 接口速览

| 端点 | 作用 | 关键返回 |
|------|------|---------|
| `POST https://opencode.ai/zen/go/v1/chat/completions` | 对话 | 标准 `usage`（含缓存明细） |
| `GET  https://opencode.ai/zen/go/v1/usage` | 查配额 | `rolling/weekly/monthly` 三窗口 `percent + resetsAt` |
| `GET  https://opencode.ai/zen/go/v1/models` | 模型列表 | 只给 `id`，无价格/缓存元数据 |

## 1. `/zen/go/v1/usage`

只返回三窗口的百分比 + 重置时间：

```json
{ "usage": {
    "rolling":  { "status": "ok", "percent": 11, "resetsAt": "2026-08-17T17:10:09.580Z" },
    "weekly":   { "status": "ok", "percent": 4,  "resetsAt": "2026-08-24T00:00:00.580Z" },
    "monthly":  { "status": "ok", "percent": 2,  "resetsAt": "2026-09-13T04:26:00.580Z" }
} }
```

结论：
- 窗口：`rolling`（5h）/ `weekly` / `monthly`。
- **无 `used/limit/remaining` 金额明细**；「还差多少」只能由 `percent` 反推。
- 确切美元金额只在 OpenCode console（`https://opencode.ai/auth`），API 不提供。
- 该调用**不消耗 Go 套餐美元额度**（纯账户状态读取，非推理）。

## 2. `/zen/go/v1/chat/completions`

响应带标准 `usage`（含缓存明细）：

```json
{
  "prompt_tokens": 9, "completion_tokens": 2, "total_tokens": 11,
  "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": null }
}
```

结论：
- `cached_tokens` = 缓存命中；`cache_write_tokens` = 缓存写入。
- `cost` 恒为字符串 `"0"` —— Go 是包月制（$10/月），无逐次金额。
- 金额只能**估算**：token 数 × 内置价格表（含峰谷），见 `src/core/pricing.ts`。
- 缓存命中依赖前缀对齐/积累；Session 粘合是为让前缀缓存持续命中。缓存命中率 = `cached / prompt`。

## 3. `/zen/go/v1/models`

- 只给 `id`，无价格/缓存元数据。
- 价格表是静态文档数据（`opencode.ai/docs/go/`），需内置。

## 4. DeepSeek V4 峰谷价（官方文档，内置）

| 项目 | 非峰值 | 峰值 |
|------|--------|------|
| 输入 | $0.22 | $0.44 |
| 输出 | $0.66 | $1.32 |
| 缓存读 | $0.007 | $0.014 |

峰谷时段：DeepSeek V4 Peak(UTC) 01-04 与 06-10 → 北京 +8：`09:00-12:00` 与 `14:00-18:00`（忙时 Peak）。