创建显式缓存
/v1/cachedContents创建可供生成请求复用的 Gemini 上下文。可用性取决于所选模型。
/v1 为默认版本,兼容对应的 /v1beta 路径。
身份验证
在 x-goog-api-key 中发送 Token360 API Key。
请求体
modelstringrequired模型名称,例如 gemini-2.5-flash 或 models/gemini-2.5-flash。
contentsobject[]要缓存的 Gemini contents。输入须满足所选模型的内容及最小 Token 数量要求。
systemInstructionobject要缓存的系统指令,使用 Gemini Content 格式。
toolsobject[]要缓存的 Gemini 工具定义,取决于模型支持情况。
tools.typestringTool type, usually function.
tools.functionobjectFunction definition.
toolConfigobject要缓存的 Gemini 工具配置,取决于模型支持情况。
displayNamestring可选的显示名称。
ttlstring有效时长(秒),例如 3600s。必须大于零且不超过 86400s(24 小时)。未设置有效期字段时默认为 3600s。与 expireTime 互斥。
expireTimestring未来的 RFC3339 时间戳,不超过当前时间之后 24 小时。用于替代 ttl。
仅接受上述字段。支持文本和 inlineData,具体取决于模型;不支持 fileData 引用。必须具有内容保留权限。
响应
namestring缓存资源名称,格式为 cachedContents/{id}。请保存用于后续操作。
modelstring模型名称,格式为 models/{model}。
displayNamestring显示名称(若返回)。
createTimestring创建时间(RFC3339,若返回)。
updateTimestring最后更新时间(RFC3339,若返回)。
expireTimestring到期时间(RFC3339,若返回)。
usageMetadataobject缓存用量信息(若返回)。
usageMetadata.totalTokenCountinteger缓存 Token 数量(若返回)。
使用缓存
保存返回的 name,通过 cachedContent 传给 POST /v1/models/{model}:generateContent 或 POST /v1/models/{model}:streamGenerateContent?alt=sse。必须使用创建缓存时的模型,仅发送新增的对话输入。不要重复发送已缓存的系统指令或工具;字段组合须符合所选模型的规则。
1{
2 "cachedContent": "cachedContents/0123456789abcdef0123456789abcdef",
3 "contents": [
4 {
5 "role": "user",
6 "parts": [
7 {
8 "text": "Summarize the reference document."
9 }
10 ]
11 }
12 ]
13}countTokens 不支持显式缓存引用。发送 cachedContent(包括放在 generateContentRequest 内或使用 snake_case 别名)时,即使已启用显式缓存,也会返回 HTTP 501,状态为 UNIMPLEMENTED。
缓存有效期
创建请求不具备幂等性。结果不明确时重试可能产生新的缓存,请勿盲目重试。请在到期前更新有效期,或在不再使用时删除资源。
错误
| 400 | 字段或有效期无效、模型不支持,或缓存内容不足。 |
| 401 / 403 | 身份验证、模型访问或内容保留权限被拒绝。 |
| 404 | 缓存不存在、已到期或不属于当前身份;或模型不存在。 |
| 409 | 缓存正被并发更新,或无法执行此操作。 |
| 413 | 请求体超过大小限制。 |
| 429 | 超出请求限制或服务容量。 |
| 501 | 未启用显式缓存。 |
| 502 / 503 | 无法完成缓存操作,请稍后重试。 |
查询已结算的创建和存储费用,请使用查询缓存账单。