Prompt Caching API

最后更新:

用 Anthropic Messages 的 cache_control 演示缓存结构,区分普通输入、缓存读写与输出,按实际 usage、长度档位和模型报价核对。

先区分缓存协议与收费字段

本例使用当前模型明确开放的 Anthropic Messages 路径,通过内容块 cache_control 声明缓存断点。缓存有最小长度、有效期与前缀一致性等条件;声明断点不能保证写入或命中。下表是 claude-sonnet-5-5 的基础标量报价,若存在长度分档,以后面的完整档位为准。

计费项当前人民币报价
普通输入¥2 / 1M tokens
输出¥10 / 1M tokens
缓存读取¥0.2 / 1M tokens
缓存写入¥2.5 / 1M tokens

最小请求示例

凭据从 KKAI_API_KEY 环境变量读取。示例是请求合同,运行后需核对实际响应和用量。

import os
import requests

r = requests.post("https://api.kkaiapi.com/v1/messages",
    headers={"x-api-key": os.environ["KKAI_API_KEY"],
             "anthropic-version": "2023-06-01", "Content-Type": "application/json"},
    json={"model": "claude-sonnet-5-5", "max_tokens": 128, "messages": [{"role": "user", "content": [{"type": "text", "text": "在这里放需要重复使用的足够长的固定上下文。此短文本只演示结构,不保证产生缓存命中。", "cache_control": {"type": "ephemeral"}}]}]}, timeout=120)
r.raise_for_status()
print(r.json())

按实际 usage 计算而非重复提示次数

Messages 的 input_tokens 为未缓存输入,另计 cache_read_input_tokens 与 cache_creation_input_tokens,再加 output_tokens;不能把缓存读写重复加进普通输入。OpenAI 兼容响应的 prompt_tokens 通常含缓存,读取量在 prompt_tokens_details.cached_tokens;两种口径先归一再计算。未返回字段不能当作已经命中。

长度档位与缓存条件

¥2 输入 / ¥10 输出 / 1M tokens

按模型页的当前报价与条件核对。

含缓存的总输入决定对应整次请求档位;缓存写入的保留时长及费率也需匹配实际合同。

验证一次写入与后续读取

对同一模型重复使用足够长的相同前缀,记录每次返回的读写 usage 与实际费用;短示例只说明请求结构。示例中的短前缀不满足生产缓存验收条件;以实际读写 usage 和费用确认命中与节省比例。

常见问题

本页示例代表已经实测成功吗?

示例说明当前请求结构与配置方式。请在自己的运行环境核对响应、模型 ID 与用量;模型快照和文档不能替代一次真实业务验收。