> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# 用量与账单

> Credits、tier、响应元数据和成本控制

JoyToken 会在模型调用成功后记录 tokens、Credits、模型、tier 和 API Key 归因。

## 你需要看什么

| 问题            | 看哪里                                                                |
| ------------- | ------------------------------------------------------------------ |
| 使用了哪个模型设置     | `metadata.model`                                                   |
| 消耗多少 Credits  | `metadata.billing.credits_used`                                    |
| 输入 / 输出 token | `metadata.billing.input_tokens` / `metadata.billing.output_tokens` |
| 哪把 Key 产生用量   | JoyToken Console 日志和用量                                             |
| 使用哪个 tier     | `metadata.tier`                                                    |

## 响应账单字段

`metadata` 始终是**数组**。单模型响应只有一条；编排响应每个任务一条。总费用应将所有条目的 `billing.credits_used` 相加。

```json
{
  "metadata": [
    {
      "model": "auto",
      "tier": "standard",
      "billing": {
        "credits_used": "0.2288",
        "input_tokens": 54,
        "output_tokens": 545
      }
    }
  ]
}
```

流式会在 `[DONE]` 前追加独立 metadata 事件：单模型响应发出一个事件，值为单元素数组；编排响应每个任务发出一个事件，值为单个对象。

## 用量归因

建议每个环境和 workflow 使用独立 API Key：

| Workflow                | 推荐 Key            |
| ----------------------- | ----------------- |
| 本地开发                    | `dev-chat-api`    |
| 集成接口                    | `integration-api` |
| OpenClaw / Hermes / IDE | `agent-key`       |
| 后台任务                    | `worker-summary`  |

## 控制成本

| 目标          | 做法                                     |
| ----------- | -------------------------------------- |
| 防止测试消耗过高    | 给测试 Key 设置较小预算                         |
| 控制 Agent 成本 | Agent / IDE 使用独立 Key 和预算               |
| 降低默认成本      | 使用 `model: "auto"` + `tier: "economy"` |
| 稳定实验成本      | 固定 tier 或 Key 预算                       |
| 排查单次调用      | 每次服务端请求带 `X-Request-ID`                |

## 余额不足

`402 insufficient_quota` 通常来自主钱包余额或 Key 预算不足。处理顺序：

1. 检查个人或组织主钱包余额。
2. 检查 API Key 的每日/每周预算。
3. 如果自动路由没有候选模型，检查 tier、策略、钱包和 Key 预算。