用量

每一次调用花了多少 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 倍估算，并用你自己的真实流量去测。

查询余额

余额、冻结金额以及每一笔费用（文本与视频，按 Key 区分）都可以在 国内预览说明 中查看。金额以美元计，保留六位小数，不涉及汇率。可用余额为负或不足时，新的付费调用会被拒绝，查询与充值不受影响。

GET /v1/usage 已下线，现在返回 404。要查看 Key 可以调用哪些模型，请使用 GET /v1/models。

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

列表中的模型仍可能返回容量不足错误，价格页只列出我们最近确认可用的模型。

我们不提供什么

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

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