> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sub2api.ruilinlu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 控制台。

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

## API 响应中的缓存字段

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

### Anthropic Claude 格式

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

```json theme={null}
{
  "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` 字段中以不同字段名呈现：

```json theme={null}
{
  "usage": {
    "prompt_tokens": 2500,
    "completion_tokens": 150,
    "total_tokens": 2650,
    "prompt_tokens_details": {
      "cached_tokens": 500
    }
  }
}
```

## 支持缓存的模型

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

  以下信息待定：

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

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

## 直觉与注意事项

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

## 相关文档

<CardGroup cols={2}>
  <Card title="Token 计费" href="/billing/token-billing">
    了解 Token 的基本计费方式
  </Card>

  <Card title="模型倍率" href="/billing/model-multiplier">
    查看不同模型的计费倍率说明
  </Card>

  <Card title="用量查询" href="/billing/usage-query">
    在控制台查看缓存命中带来的费用节省
  </Card>
</CardGroup>