OpenRouter 每个 API 响应都自动包含完整的 usage 统计字段，无需额外参数。usage 对象提供 prompt_tokens、completion_tokens（含 reasoning_tokens 明细）、total_tokens，以及 cost（总费用）和 cost_details.upstream_inference_cost（仅 BYOK 适用）。缓存相关字段在 prompt_tokens_details 中：cached_tokens（缓存命中读取量）和 cache_write_tokens（首次写入缓存量）。streaming 响应中 usage 在最后一个 SSE chunk 中返回。

OpenRouter 在每个 API 响应中自动返回详细的用量统计信息，无需额外参数或配置。

响应格式

每个响应都包含 usage 对象：

{
  "object": "chat.completion.chunk",
  "usage": {
    "completion_tokens": 2,
    "completion_tokens_details": {
      "reasoning_tokens": 0
    },
    "cost": 0.95,
    "cost_details": {
      "upstream_inference_cost": 19
    },
    "prompt_tokens": 194,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 100,
      "audio_tokens": 0
    },
    "total_tokens": 196
  }
}

废弃参数：usage: { include: true } 和 stream_options: { include_usage: true } 已废弃，无效。完整用量统计现在始终自动包含在响应中。

字段说明

字段	说明
prompt_tokens	输入 prompt 的 token 数
completion_tokens	输出内容的 token 数
total_tokens	prompt + completion 合计
completion_tokens_details.reasoning_tokens	思考过程消耗的 reasoning token 数
cost	本次请求从你账号扣除的总费用（credits）
cost_details.upstream_inference_cost	上游 provider 实际收费（仅 BYOK 适用）
prompt_tokens_details.cached_tokens	从缓存中读取的 token 数（缓存命中）
prompt_tokens_details.cache_write_tokens	写入缓存的 token 数（首次建立缓存条目时）

Streaming 模式

Streaming 响应中，usage 字段包含在最后一个 SSE chunk 中。监听 streaming chunk 时需检查每个 chunk 的 usage 字段是否存在。

代码示例

TypeScript

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const response = await openRouter.chat.send({
  model: 'anthropic/claude-3-opus',
  messages: [
    {
      role: 'user',
      content: 'What is the capital of France?',
    },
  ],
});

console.log('Response:', response.choices[0].message.content);
console.log('Usage Stats:', response.usage);

Python（streaming）

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="<OPENROUTER_API_KEY>",
)

for chunk in client.chat.completions.create(
    model="anthropic/claude-3-opus",
    messages=[{"role": "user", "content": "Write a haiku about Paris."}],
    stream=True
):
    if hasattr(chunk, 'usage') and chunk.usage:
        if hasattr(chunk.usage, 'total_tokens'):
            print(f"\nUsage Statistics:")
            print(f"Total Tokens: {chunk.usage.total_tokens}")
            print(f"Prompt Tokens: {chunk.usage.prompt_tokens}")
            print(f"Completion Tokens: {chunk.usage.completion_tokens}")
            print(f"Cost: {chunk.usage.cost} credits")
    elif chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

通过 Generation ID 查询

也可以通过请求响应中的 id 字段异步查询用量，适合事后审计或延迟统计：

1. 正常发送 chat completion 请求
2. 记录响应中的 id 字段
3. 通过 /api/v1/generation?id={id} 端点查询用量详情

详见 Get a Generation 文档。

常见问题

Q: 每次请求都会包含 usage 吗？

A: 是的，无论是否 streaming、无论使用哪个模型，每次响应都会自动包含 usage 字段。不需要任何额外参数。

Q: cost 和 upstream_inference_cost 有什么区别？

A: cost 是从你 OpenRouter 账号扣除的总积分。upstream_inference_cost 只在 BYOK 模式下返回，表示上游 provider 实际向你收取的费用，两者可能有差异（因路由、手续费等因素）。

Q: cached_tokens 为 0 是否表示没有缓存命中？

A: 是的，cached_tokens > 0 表示有内容从缓存中读取并节省了费用。cache_write_tokens > 0 表示本次请求新建了缓存条目（下次请求才能命中）。