Sub2API Cached Token 说明

了解 Cached Token 的含义、如何产生缓存命中，以及缓存命中对 API 调用成本的影响。

部分模型支持 Prompt Caching（提示缓存）功能。当你的请求包含较长的重复前缀（如固定的系统提示或共享上下文）时，缓存机制可以自动复用已处理的内容，从而降低 API 调用成本。本文档说明缓存的工作原理、如何识别缓存命中，以及它对计费的影响。

什么是 Prompt Caching

Prompt Caching 是一种优化机制：当模型检测到请求中的部分内容与之前处理过的内容高度重复时，会自动复用之前的处理结果，而不是从头开始计算。这使得包含重复上下文的请求费用更低。

适用场景

Prompt Caching 通常在以下场景生效：

• 固定系统提示：每次请求都包含相同或相似的长系统提示
• 共享上下文：多个请求共享相同的长文档或背景信息
• 重复任务：在批量处理相似任务时，大量提示内容相同

缓存命中对计费的影响

缓存命中后，这部分 Token 的费用会显著低于普通输入 Token：

• 缓存读取 Token（Cache Read）：命中缓存的 Token，费用低于普通输入 Token
• 缓存创建 Token（Cache Creation）：首次处理并写入缓存的 Token
• 普通输入 Token：未命中缓存的 Token，按标准输入 Token 计费

不同模型的缓存折扣率不同。具体折扣请参考 Sub2API 控制台。

Prompt Caching 是自动生效的，你不需要手动启用或配置。只要使用支持缓存的模型并且满足缓存条件，系统会自动应用缓存计费。

API 响应中的缓存字段

在支持缓存的模型响应中，usage 字段会包含缓存相关的统计信息。

Anthropic Claude 格式

对于 Claude 等模型，响应中的 usage 字段可能包含：

{
  "usage": {
    "input_tokens": 2500,
    "output_tokens": 150,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 500
  }
}

字段说明

字段	含义
input_tokens	总输入 Token 数量
output_tokens	输出 Token 数量
cache_creation_input_tokens	首次写入缓存的 Token 数量
cache_read_input_tokens	命中缓存的 Token 数量（费用更低）

OpenAI 兼容格式

对于 OpenAI 兼容格式的响应，缓存信息可能在 usage 字段中以不同字段名呈现：

{
  "usage": {
    "prompt_tokens": 2500,
    "completion_tokens": 150,
    "total_tokens": 2650,
    "prompt_tokens_details": {
      "cached_tokens": 500
    }
  }
}

支持缓存的模型

TODO：请在后台确认实际配置后填写。

以下信息待定：

• 哪些模型支持 Prompt Caching
• 缓存折扣的具体比例
• 缓存的最小 Token 触发阈值

一般来说，较新的模型（如 Claude 3.5 Sonnet、GPT-4o 等）更可能支持缓存功能。请登录 Sub2API 控制台查看你使用的模型是否支持缓存。

直觉与注意事项

1. 缓存不是永久保存的：缓存内容有一定的生命周期，过期的缓存会自动失效
2. 部分匹配不触发缓存：只有完全匹配的前缀内容才能触发缓存命中
3. 首次调用费用不变：第一次发送长提示时，不会产生缓存读取折扣，系统需要先创建缓存
4. 缓存折扣因模型而异：不同模型的缓存折扣率可能不同

相关文档

Token 计费

了解 Token 的基本计费方式

模型倍率

查看不同模型的计费倍率说明

用量查询

在控制台查看缓存命中带来的费用节省