用量

每一次调用花了多少 token、缓存有没有命中、余额还剩多少。

响应里报告了什么

每个响应都带一个 usage 块：

"usage": {
  "input_tokens": 24,
  "output_tokens": 4,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0
}

计费按 input_tokens 与 output_tokens， 缓存 token 单独计价，见下。

流式请求怎么读

流式响应把用量分两处上报：message_start 事件里带输入侧的数字， message_delta 事件里带最终的 output_tokens。 两个都要读，只读其一会漏。

区分缓存命中和缓存写入

在稳定前缀上打一个缓存断点：

"messages": [{"role": "user", "content": [
  {"type": "text", "text": "<你的长而稳定的前缀>",
   "cache_control": {"type": "ephemeral"}},
  {"type": "text", "text": "<变化的部分>"}
]}]

然后读回这两个数：

• cache_creation_input_tokens > 0 —— 写入。你按 1.25× 付费填充缓存。
• cache_read_input_tokens > 0 —— 命中。你按 0.10× 付费。

各模型的计量差异

claude-opus-5 使用与其他六个模型不同的容量，因此计量方式也不同。

它对输入 token 的计数更宽松。英文散文实测约为你预期的 1.67 倍，另外每个请求还有大约 530 token 的固定开销。中文和代码我们测到的单位计数更高， 但还没有定出确切比例，请按至少 1.67 倍估算，并用你自己的真实流量去测。

查询余额

金额统一为美元，保留六位小数，不再换汇。这里的余额与 Console 一致：账户充值减去文字和视频已扣费用，可以为负数。可用余额是余额再减去占款。可用余额不足时，新的付费请求会被拒绝，查询和充值仍可使用。spend_usd 和 balance_usd 从旧版的单密钥统计改为账户统计；limit_usd、key_spend_usd、key_remaining_usd 仍表示当前密钥的额度、已扣费用和未扣占款的剩余额度。密钥额度只限制文字请求，视频使用账户可用余额。未设置有效的文字额度时，limit_usd 和 key_remaining_usd 为 null，仍可正常查询余额。旧版 *_cny 字段和 fx 对象已移除。

curl https://api.nightferry.io/v1/usage -H "x-api-key: $NIGHTFERRY_KEY"

{"currency": "USD", "spend_usd": "0.180000", "balance_usd": "14.650000",
 "text_spend_usd": "0.042697", "video_spend_usd": "0.137303",
 "held_usd": "0.171631", "available_usd": "14.478369",
 "limit_usd": "14.830000", "key_spend_usd": "0.180000",
 "key_remaining_usd": "14.650000", "models": ["..."]}

models 是这个密钥被授权调用的模型清单。 它与我们此刻实际能提供的服务不完全等同 —— 清单上的模型仍可能返回无可用容量错误。

我们不提供什么

/v1/messages/count_tokens 在 Anthropic API 里存在， 但这里不提供。我们不服务该接口，而且我们能返回的数字会忽略你的 tools 和 system 块 —— 在真实的 agent 负载上，误差超过三十倍。 一个看起来对、实际错的数字比没有数字更糟，所以它返回 404。

要在发送前估算 prompt 大小，就把它发出去，然后读回 usage。 失败的请求不计费 —— 见错误。