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

# 提示缓存：重复发送的上下文至少便宜 10 倍

> RuAPI 的提示缓存怎么用：Claude 走原生 Anthropic 接口或 OpenAI 兼容格式（cache_control）都能缓存，GPT 和 DeepSeek 自动缓存；价格说明，以及怎么确认命中了缓存。

编程智能体和聊天机器人会一遍又一遍地把同样的上下文发给模型：系统提示、项目文件、对话历史。在智能体场景里，这部分通常占全部输入 token 的 80–97%。有了提示缓存，这些重复的上下文就不用再按全价付费：模型记住已经处理过的请求开头，再次从缓存读取时，价格至少比普通输入便宜 10 倍。

## RuAPI 能做到什么

* **Claude 走原生 Anthropic 接口：和直连 Anthropic 一样**。发到 `https://www.ruapi.ai/v1/messages` 的请求，缓存标记 `cache_control` 原样转给 Claude，包括 `ttl`。Claude Code、Anthropic SDK，以及选了 Anthropic 提供商的智能体，不用额外设置就有缓存。
* **Claude 走 OpenAI 兼容格式：也能缓存**。消息内容块上的 `cache_control` 标记，RuAPI 会转给 Claude；请求最外层的一个标记（自动缓存）也能识别。写法和 OpenRouter 一样。Anthropic 官方自己的 OpenAI 兼容接口不支持缓存。
* **GPT 和 DeepSeek：自动缓存**。请求开头重复时自动命中缓存，什么都不用设置。
* **用量清楚可查**。API 返回里写明有多少 token 从缓存读取、多少写入缓存，控制台里每条请求也能看到。
* **不用 VPN，不用境外银行卡**。RuAPI 在俄罗斯可以直接访问，余额用 USDT 充值。

## 价格

| 项目 | 价格 |
| - | - |
| 缓存读取（Claude） | 至少比普通输入便宜 10 倍 |
| 写入 5 分钟缓存（Claude） | 输入价的 1.25 倍 |
| 写入 1 小时缓存（Claude） | 输入价的 2 倍 |
| 输出 | 按原价：输出不缓存 |

各模型的准确价格见[价格页](https://www.ruapi.ai/pricing?lng=zh-CN\&utm_source=docs\&utm_campaign=zh-prompt-caching)。写入缓存比普通输入稍贵，所以同样的上下文只要在缓存有效期内发第二次，就开始省钱了。每命中一次，缓存有效期都会再延长 5 分钟（或 1 小时）。

## Claude：怎么开启缓存

### 先看用的是哪种格式

同一把 RuAPI 密钥可以用两种格式调 Claude：Anthropic 原生格式和 OpenAI 兼容格式。缓存怎么开，要看你用的是哪一种。不确定的话，下面任选一处看：

| 在哪里看 | OpenAI 兼容格式 | Anthropic 原生格式 |
| - | - | - |
| 控制台 **使用日志** 里打开一条记录，看「请求路径」 | `/v1/chat/completions` | `/v1/messages` |
| 工具里选的提供商 | OpenAI、OpenAI Compatible 或自定义 OpenAI | Anthropic 或 Claude |
| 自己写的代码 | 用 `openai` 库 | 用 `anthropic` 库 |

Claude Code 用的一直是 Anthropic 原生格式，会自己打缓存标记，不用查。用 OpenAI 兼容格式时，只有请求里带了 `cache_control` 标记才会缓存。两种格式的完整区别见[OpenAI 格式还是 Anthropic 格式](/zh/openai-vs-anthropic-format)。

### Claude Code 和编程智能体

| 工具 | 怎么做 |
| - | - |
| [Claude Code](/zh/integrations/claude-code) | 什么都不用做：Claude Code 会自己打缓存标记 |
| [Cline](/zh/integrations/cline)、[Roo Code](/zh/integrations/roo-code) | 选 **Anthropic** 提供商，地址填 `https://www.ruapi.ai` |
| [Kilo Code](/zh/integrations/kilo-code) | 选 **Anthropic Messages** 提供商，地址填 `https://www.ruapi.ai/v1` |
| [Continue](/zh/integrations/continue) | `provider: anthropic`，再加 `promptCaching: true` |
| [OpenCode](/zh/integrations/opencode) | 内置的 `anthropic` 提供商，地址填 `https://www.ruapi.ai/v1` |

<Tip>
  如果智能体里给 Claude 选的是 **OpenAI Compatible** 提供商，只有智能体自己打了 `cache_control` 标记才会缓存。大多数智能体在这种模式下不打标记，所以用 Claude 时更稳妥的做法是选 Anthropic 提供商。
</Tip>

### 自己写的程序：Anthropic SDK

把 `cache_control` 标记打在请求中不变部分的最后一个块上，比如很长的系统提示。标记之前的内容都会进缓存。

```python theme={null}
import anthropic

client = anthropic.Anthropic(base_url="https://www.ruapi.ai", api_key="sk-...")

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,  # 说明、文档、项目代码
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "你的问题"}],
)
print(response.usage.cache_read_input_tokens, response.usage.cache_creation_input_tokens)
```

想让缓存保留 1 小时而不是 5 分钟，写成 `"cache_control": {"type": "ephemeral", "ttl": "1h"}`。

### 自己写的程序：OpenAI SDK

OpenAI 兼容格式里，标记打在 `content` 的某个块上，所以带标记的消息要把内容写成块的列表，不能写成字符串。

```python theme={null}
from openai import OpenAI

client = OpenAI(base_url="https://www.ruapi.ai/v1", api_key="sk-...")

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": LONG_SYSTEM_PROMPT,
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "你的问题"},
    ],
)
print(response.usage.prompt_tokens_details.cached_tokens)
```

也可以只在请求最外层打一个 `cache_control` 标记，Anthropic 把这叫作自动缓存。这时 RuAPI 会像 Anthropic 一样，自己把标记打在最后一条消息的最后一个块上，所以这种写法在我们所有的 Claude 渠道上都能用。每多一条消息，标记就往后挪一条，之前的对话都会进缓存。

<Note>
  一个请求最多打 4 个标记。请求开头太短不会缓存，最短长度因模型而异，例如 Claude Sonnet 5.5 和 Claude Opus 5.5 是 512 个 token。
</Note>

## GPT 和 DeepSeek：自动缓存

* **GPT**。请求开头至少 1024 个 token 和最近的请求一样时，相同的部分会从缓存读取，不用打标记。
* **DeepSeek**。缓存一直开着：重复的请求开头按缓存命中价计费。

想让缓存命中得更多，就把不变的部分（系统提示、说明、工具定义）放在请求开头，会变的内容放在最后。

## 怎么确认命中了缓存

| 格式 | 从缓存读取 | 写入缓存 |
| - | - | - |
| Anthropic（`/v1/messages`） | `usage.cache_read_input_tokens` | `usage.cache_creation_input_tokens` |
| OpenAI（`/v1/chat/completions`） | `usage.prompt_tokens_details.cached_tokens` | `usage.prompt_tokens_details.cached_creation_tokens`（Claude） |

OpenAI 格式里的 `prompt_tokens` 已经包含缓存的 token，和 OpenAI 的算法一样。控制台里每条请求也能看到：**使用日志** → 打开记录详情。

## 对比

| | RuAPI | 直连 Anthropic | OpenRouter |
| - | - | - | - |
| 在俄罗斯不用 VPN 能否访问 | 能 | 不能：俄罗斯不在支持的国家名单里 | 不能：俄罗斯 IP 访问返回 403 |
| Claude 走原生 Anthropic 接口时缓存 | 支持 | 支持 | 支持 |
| Claude 走 OpenAI 兼容格式时缓存 | 支持：内容块上和最外层的 `cache_control` 标记 | 不支持：OpenAI 兼容接口不支持缓存 | 支持：内容块上的标记；最外层的只在转到 Anthropic 本身时有效 |
| 付款方式 | USDT、境外银行发行的卡 | 银行卡 | 银行卡、USDC |

其他服务的情况来自 [Anthropic](https://docs.anthropic.com/en/api/openai-sdk) 和 [OpenRouter](https://openrouter.ai/docs/features/prompt-caching) 的官方文档（2026 年 10 月 15 日核对）；OpenRouter 返回 403 来自我们 2026 年 9 月 30 日的检测。

## 常见问题

<AccordionGroup>
  <Accordion title="为什么没有命中缓存？">
    * 请求开头变了。标记之前哪怕只差一个字符，比如当前时间、随机 ID，都算新的开头，会重新写入缓存。
    * 请求开头太短，达不到这个模型的最短长度。
    * 超过 5 分钟没有请求（设了 `"ttl": "1h"` 的是 1 小时）。
    * 用 OpenAI 兼容格式调 Claude，但没打 `cache_control` 标记。
  </Accordion>

  <Accordion title="Claude 扣费很快、余额掉得快，要查什么？">
    多半是缓存没有生效，重复的上下文每次都按全价计费。

    1. 先看用的是哪种格式：在控制台 **使用日志** 里打开一条 Claude 的记录，看「请求路径」。是 `/v1/messages` 的，是 Anthropic 原生格式，缓存和直连 Anthropic 一样（Claude Code 会自己打标记），没命中的原因看上一条。是 `/v1/chat/completions` 的，是 OpenAI 兼容格式，接着看下面几步。其他判断办法见本页「先看用的是哪种格式」。
    2. 看缓存有没有生效：记录详情里有「缓存 Tokens」这一行，就是命中了；重复的请求一直没有这一行，就是没生效。自己写的程序也可以看 API 返回里的 `usage.prompt_tokens_details.cached_tokens`。
    3. 看客户端有没有打 `cache_control` 标记：没有标记，Claude 什么都不缓存。很多智能体在 **OpenAI Compatible** 模式下不打标记，在智能体里改选 Anthropic 提供商就行。自己写的程序，在请求最外层打一个 `cache_control` 标记就够了。
    4. 如果用的是别家网关，查一下它的文档：OpenAI 兼容格式下支不支持 Claude 缓存。不是每家都支持：Anthropic 官方自己的 OpenAI 兼容接口就不支持缓存；再比如 APIYI 的文档写明，Claude 的缓存折扣只在原生 Anthropic 格式下才有（2026 年 10 月 15 日核对）。在 RuAPI，两种格式下 Claude 都能缓存。
  </Accordion>

  <Accordion title="缓存要额外收费吗？">
    写入缓存按普通输入价的 1.25 倍收费（1 小时缓存是 2 倍），但之后每次读取都至少便宜 10 倍。同样的上下文只要发两次以上，就已经省钱了。
  </Accordion>

  <Accordion title="要在 RuAPI 控制台里开什么吗？">
    不用。任何密钥都能用缓存：Claude 只要有 `cache_control` 标记（Claude Code 会自己打），GPT 和 DeepSeek 自动缓存。
  </Accordion>
</AccordionGroup>

## 接下来

* [Claude Code](/zh/integrations/claude-code)：接好就有缓存，不用额外设置。
* [价格](/zh/pricing)：缓存怎么影响最终费用。
* [DeepSeek 还是 Claude：一天的活儿到底花多少钱](/zh/deepseek-vs-claude)：带缓存的真实账单拆解。
* [Claude Code 和 Cline 怎么省钱](/zh/claude-code-cline-costs)：哪些操作会让缓存失效，怎么让上下文保持精简。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.