创建显式缓存

POST/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.typestring

Tool type, usually function.

tools.functionobject

Function 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。必须使用创建缓存时的模型,仅发送新增的对话输入。不要重复发送已缓存的系统指令或工具;字段组合须符合所选模型的规则。

JSON
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无法完成缓存操作,请稍后重试。

查询已结算的创建和存储费用,请使用查询缓存账单。

请求

1jq -n --rawfile text context.txt '{
2  model: "gemini-2.5-flash",
3  displayName: "Reference document",
4  contents: [{role: "user", parts: [{text: $text}]}],
5  ttl: "3600s"
6}' | curl --fail-with-body 'https://api.token360.ai/v1/cachedContents' \
7  -H "x-goog-api-key: $TOKEN360_API_KEY" \
8  -H 'Content-Type: application/json' \
9  --data-binary @-

响应

JSON
1{
2  "name": "cachedContents/0123456789abcdef0123456789abcdef",
3  "model": "models/gemini-2.5-flash",
4  "displayName": "Reference document",
5  "createTime": "2026-11-06T10:00:00Z",
6  "updateTime": "2026-11-06T10:00:00Z",
7  "expireTime": "2026-11-06T11:00:00Z",
8  "usageMetadata": {
9    "totalTokenCount": 4096
10  }
11}
此页面对您有帮助吗?
创建显式缓存 · Token360