> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# Token 用量与计费说明
> 了解算秩 Model Inference 的 token 类型、计费公式、Reasoning Tokens、Output Tokens 和 max_completion_tokens 的关系。
Model Inference 采用按量计费，依据实际 token 用量和所调用模型的单价结算。不同模型的单价可能不同，具体价格请以 [模型广场](https://console.siflow.cn/model-inference/models) 中的模型详情页为准。
## Token 类型
一次请求通常由输入、缓存读、缓存写和输出等计费项构成。各类 token 的统计口径如下：
| 类型 | 说明 |
| ---------------------------------- | ------------------------------------------------------------------------ |
| 输入 Tokens（Input Tokens） | 未命中缓存、需要重新计算的输入 token，包括 `system`、`user`、`assistant` 历史消息、上下文材料、工具定义等。 |
| 图像输入 Tokens（Image Input Tokens） | 视觉输入按模型规则折算后的 token，是输入 Tokens 的组成部分，出现在视觉与多模态模型中。 |
| 缓存读 Tokens（Cache Read Tokens） | 本次请求命中并复用缓存的输入 token。 |
| 缓存写 Tokens（Cache Write Tokens） | 本次请求写入缓存、供后续请求复用的输入 token。仅当模型支持 Prompt Caching，且本次请求确实创建缓存条目时产生。 |
| 输出 Tokens（Output Tokens） | 模型为本次请求生成的全部 token，而不只是最终可见回答。对于推理模型，输出 Tokens 包含推理 Tokens 和可见输出 Tokens。 |
| 可见输出 Tokens（Visible Output Tokens） | 最终返回给用户可见的回答 token，通常对应响应中的 `content`。 |
| 推理 Tokens（Reasoning Tokens） | 推理模型内部推理消耗的 token。它们可能在 API 响应中返回，也可能不作为可见内容返回。 |
| 总 Tokens（Total Tokens） | 本次请求统计的总 token，通常包含输入 Tokens、缓存读 Tokens、缓存写 Tokens 和输出 Tokens。 |
推理 Tokens 是否在 API 响应中返回，取决于具体模型、协议和请求参数。有些模型会返回 `reasoning` 或 `reasoning_content`，有些模型不会。即使推理 Tokens 不作为可见内容返回，也会进入平台用量统计。
## 计费公式
Model Inference 的完整计费公式如下：
**费用 = 输入 Tokens × 输入单价 + 缓存读 Tokens × 缓存读单价 + 缓存写 Tokens × 缓存写单价 + 输出 Tokens × 输出单价**
* 输入、缓存读、缓存写和输出都有独立单价，具体以模型广场的模型详情页为准。
* 图像输入折算为输入 Tokens 后，按输入单价计费。
不同模型类型的计费项说明如下：
| 模型类型 | 说明 |
| -------- | ---------------------------------------------------------------------- |
| 文本模型 | 通常包含输入 Tokens 和输出 Tokens。如果请求没有使用 Prompt Caching，对应缓存项为 0。 |
| 推理模型 | 输出 Tokens 包含推理 Tokens 和可见输出 Tokens。当前平台计费口径下，推理 Tokens 按对应模型的输出单价参与计费。 |
| 视觉与多模态模型 | 输入 Tokens 包含文本 token 和图像 token。图像分辨率、数量和模型实现不同，都会影响图像输入 Tokens。 |
## max\_completion\_tokens
`max_completion_tokens` 限制的是生成侧总预算，也就是推理 Tokens 和可见输出 Tokens 的合计。它不是只限制最终可见回答。
如果使用推理模型，内部推理会先消耗一部分生成预算。当 `max_completion_tokens` 设置过小时，可能出现以下情况：
* 可见回答很短，但输出 Tokens 较多。
* 推理过程耗尽生成预算，导致 `content` 为空。
* 回答被截断，`finish_reason` 为 `length`。
可以通过适当增大 `max_completion_tokens`，或调整 `thinking_budget` 缓解这类问题。`thinking_budget` 是 hint，不是严格上限；模型可能参考它控制推理量，也可能只部分采用这一设置。
目前推荐使用 `max_completion_tokens`。如果您在第三方工具或旧示例中看到 `max_tokens`，它表达的是同类含义。
## 查看用量
您可以在 [使用详情](https://console.siflow.cn/model-inference/usage_detail) 页面查看单次请求的 token 用量。
使用详情会展示输入、图像输入、缓存读、缓存写、推理、输出、总 token 等字段。其中，“输出”包含“推理”，排查成本时不要重复相加。
更多信息，请参考 [查看使用详情](/model-inference/usage/view-usage)。
## 哪些请求会计费
正常完成并产生模型用量的请求会按实际 token 用量计费。在到达模型之前被拒绝的请求不计费，例如请求参数无效、鉴权失败、余额不足、无权限调用模型、模型不存在或超出速率限制。平台侧故障不计费。
各类错误的响应结构和处理方式，请参考 [错误处理](/model-inference/api/error-handling)。
## 成本控制建议
* **控制输入长度**：减少无关历史消息、长文档和重复上下文，避免输入 token 持续增长。
* **控制生成预算**：合理设置 `max_completion_tokens`，避免模型生成过长回复。
* **控制推理预算**：对推理模型合理设置 `thinking_budget`，在推理深度、延迟和成本之间做平衡。
* **选择合适模型**：开发验证阶段优先使用低成本模型，正式上线前再根据效果和成本选择目标模型。
* **复用长上下文**：对于重复长前缀、固定系统提示或多轮长材料，可参考 [Prompt 缓存](/model-inference/models/prompt-caching)。
* **稳定 prompt 前缀**：让系统消息、工具定义、few-shot 示例等稳定内容在多次请求中保持顺序和内容一致，有助于提高 Prompt Caching 命中机会。
* **按应用拆分 API Key**：为不同应用创建独立 API Key，并设置每月额度、总额度、TPM 和 RPM。更多信息请参考 [API 密钥](/model-inference/usage/api-keys)。
## 常见问题
对于推理模型，内部推理会消耗推理 Tokens。推理 Tokens 可能不作为可见内容返回，但会计入输出 Tokens，并按输出单价参与计费。因此，可见回答短不代表输出 Tokens 一定少。
`max_completion_tokens` 限制推理 Tokens 和可见输出 Tokens 的合计。如果推理过程耗尽生成预算，模型可能没有剩余预算生成最终可见回答，导致 `content` 为空。
这通常表示生成内容达到了 `max_completion_tokens` 上限，或者请求整体超过模型上下文限制。可以减少输入内容、增大 `max_completion_tokens`，或启用流式输出改善长回复体验。
API 是否返回 `reasoning` 或 `reasoning_content` 取决于模型、协议和请求参数。即使它们不作为响应内容返回，平台仍会统计模型内部推理消耗，并在用量详情中展示。
不能。`thinking_budget` 是 hint，不是严格上限。它可以帮助模型控制推理量，但不同模型对该参数的支持和采用程度可能不同。
是。每次请求都是独立的，您发送的完整对话历史都会计入本次请求的输入。Prompt Caching 可以降低重复前缀的处理成本，但不会让模型自动继承上一轮上下文。