利用提示词缓存节省资源

提示缓存机制确保相同的提示内容（长系统提示、工具定义、参考文档、对话历史记录）仅需完整处理一次。后续请求中，该部分内容将从缓存中读取，并按**正常输入费用的约10%**计费。 Hostlinku 完全沿用了 Anthropic 的缓存机制，且未针对缓存追加特殊费用；各模型的实际费率详见模型目录。

价格的运作机制

Token类型	相对于正常投入的费率	何时发生
正常输入	1×	未缓存的提示部分
缓存写入	1,25×	该区块首次被标记为`cache_control`，且尚未存入缓存
缓存读取	0,1×	同一块数据在缓存有效期内再次被发送

部分最新模型采用更低的缓存读取费率：claude-opus-5-5 和 claude-sonnet-5-5 为 0.05×，claude-fable-5-1 为 0.025×。各模型的具体数值请参见模型目录-该页面显示了原厂价格以及按服务模式划分的销售价格。默认缓存有效期为自上次使用起5分钟（每次被访问时都会延长）。这意味着，当同一数据块被使用至少2次时，缓存就已收回成本；使用频率越高，节省的成本就越大。各模型的费率详见模型目录（cache_read / cache_write列）。

每个模型的最低阈值

低于此阈值的块将不会被缓存，且 cache_creation_input_tokens / cache_read_input_tokens 的值为 0，且不会显示错误信息。

模型	可缓存的最小块
`claude-fable-5`, `claude-fable-5-1`, `claude-opus-5`, `claude-opus-5-5`, `claude-sonnet-5-5`	512 个Token
`claude-sonnet-5`, `claude-sonnet-4-6`, `claude-opus-4-8`	1,024 个Token
`claude-opus-4-7`	2,048 个Token
`claude-opus-4-6`, `claude-haiku-4-5`	4,096 个Token

提示词的构成原则

缓存基于前缀工作-所有位于标记cache_control之前的内容必须字节级完全一致，才能被命中。请按从最静态到最动态的顺序排列提示词：

tools（函数定义）-很少更改
system - 说明、角色、参考文档
messages 旧版 - 对话记录
最新用户消息-内容随时变化，请勿缓存

每个请求最多包含 4 个 cache_control 标记。最常见的情况是：在 system 的末尾有一个。

格式 Anthropic (`/v1/messages`)

由 Anthropic SDK、Claude Code、Cursor、Cline 以及其他采用 Anthropic 协议的工具使用。将 system 写入块数组，然后在最后一个静态块中指定 cache_control：

curl https://api.hostlinku.com/v1/messages \
  -H "x-api-key: sk-isi-api-key-kamu" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "<instruksi panjang + dokumen referensi di sini>",
        "cache_control": { "type": "ephemeral" }
      }
    ],
    "messages": [
      { "role": "user", "content": "Ringkas bagian 3 dokumen di atas." }
    ]
  }'

针对input_tokens的单独缓存Token报告的响应：

"usage": {
  "input_tokens": 16,
  "cache_creation_input_tokens": 3601,
  "cache_read_input_tokens": 0,
  "output_tokens": 4
}

在第二次使用相同 system 的请求中，其值变为 cache_creation_input_tokens: 0 和 cache_read_input_tokens: 3601-这表明缓存正在起作用。 Python (Anthropic SDK)

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.hostlinku.com",
    api_key="sk-isi-api-key-kamu",
)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": DOKUMEN_REFERENSI,  # konten statis & panjang
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[{"role": "user", "content": "Ringkas bagian 3."}],
)
print(resp.usage.cache_read_input_tokens)

格式 OpenAI (`/v1/chat/completions`)

对于使用 OpenAI SDK 的应用程序，请将 content 系统作为 内容部分 数组写入，并将 cache_control 放置在其部分中。Hostlinku 会将其转换为 Anthropic - 仅适用于 Claude 模型。

curl https://api.hostlinku.com/v1/chat/completions \
  -H "Authorization: Bearer sk-isi-api-key-kamu" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "type": "text",
            "text": "<instruksi panjang + dokumen referensi di sini>",
            "cache_control": { "type": "ephemeral" }
          }
        ]
      },
      { "role": "user", "content": "Ringkas bagian 3 dokumen di atas." }
    ]
  }'

usage.prompt_tokens_details 中出现了缓存Token：

"usage": {
  "prompt_tokens": 3583,
  "completion_tokens": 4,
  "prompt_tokens_details": {
    "cached_tokens": 3569,
    "cache_write_tokens": 0
  }
}

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="https://api.hostlinku.com/v1", api_key="sk-isi-api-key-kamu")

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": DOKUMEN_REFERENSI,
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "Ringkas bagian 3."},
    ],
)
print(resp.usage.prompt_tokens_details.cached_tokens)

克劳德·科德、Cursor、Cline 和 agent

这些工具已自行将 cache_control 添加到系统提示符及其工具定义中。一旦您将基础 URL 指向 Hostlinku（参见 IDE 与代理的集成），优化将自动生效-无需额外配置。在日志中，您会发现同一会话中几乎每次后续请求都会出现大量的 Cache Read 记录。

在控制台中查看

在控制台中打开请求日志。每行显示输入、输出、缓存读取、缓存写入（总计）、缓存写入 5 分钟 / 缓存写入 1 小时的详细信息，以及最终费用。每条 TTL 的详细信息仅在上游发送时才会填充-否则，该列将显示 -（而非 0），而总计仍会被记录。快速确认缓存是否正常工作的方法：

支持的模型

模型	提示缓存
所有 `claude-*`	是的-通过`cache_control`明确规定（上述两种格式）
`gpt-`, `deepseek-`, `glm-*`	来自提供商的自动处理 - 不包含 `cache_control`；若在提供商缓存有效期内再次发送相同的前缀，则会填充 `cached_tokens` / `cache_read`
`kimi-`, `qwen`, `minimax-`, `mimo-`	这取决于提供商；部分提供商尚未报告缓存数据，因此该值可能为0

还有其他问题吗？请参阅常见问题解答或联系帮助中心。

​价格的运作机制

​每个模型的最低阈值

​提示词的构成原则

​格式 Anthropic (/v1/messages)

​格式 OpenAI (/v1/chat/completions)

​克劳德·科德、Cursor、Cline 和 agent

​在控制台中查看

​支持的模型