Create explicit cache
/v1/cachedContentsCreate reusable Gemini context for generation requests. Availability depends on the selected model.
/v1 is the default version; equivalent /v1beta paths remain supported.
Authentication
Send your Token360 API key in x-goog-api-key.
Request Body
modelstringrequiredModel name, such as gemini-2.5-flash or models/gemini-2.5-flash.
contentsobject[]Gemini contents to cache. Input must meet the selected model’s content and minimum token requirements.
systemInstructionobjectSystem instruction to cache, using Gemini Content format.
toolsobject[]Gemini tool definitions to cache, subject to model support.
tools.typestringTool type, usually function.
tools.functionobjectFunction definition.
toolConfigobjectGemini tool configuration to cache, subject to model support.
displayNamestringOptional human-readable label.
ttlstringLifetime in seconds, such as 3600s. Must be greater than zero and at most 86400s (24 hours). Defaults to 3600s if neither expiration field is set. Mutually exclusive with expireTime.
expireTimestringFuture RFC3339 timestamp, at most 24 hours from now. Use instead of ttl.
Only the fields above are accepted. Text and inlineData parts are supported subject to the model; fileData references are not supported. Content-retention permission is required.
Response
namestringCache resource name: cachedContents/{id}. Save it for subsequent operations.
modelstringModel name in models/{model} form.
displayNamestringDisplay label, when returned.
createTimestringCreation timestamp (RFC3339), when returned.
updateTimestringLast update timestamp (RFC3339), when returned.
expireTimestringExpiration timestamp (RFC3339), when returned.
usageMetadataobjectCache usage information, when returned.
usageMetadata.totalTokenCountintegerNumber of cached tokens, when returned.
Use the cache
Save the returned name and send it as cachedContent to POST /v1/models/{model}:generateContent or POST /v1/models/{model}:streamGenerateContent?alt=sse. Use the same model as the cache and send only the additional conversation input. Do not resend cached system instructions or tools; follow the selected model's rules for combining these fields.
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 does not support explicit cached-content references. Sending cachedContent, including inside generateContentRequest or using snake_case aliases, returns HTTP 501 with status UNIMPLEMENTED, even when explicit caching is enabled.
Cache lifetime
Create requests are not idempotent. Retrying after an uncertain outcome can create another cache, so do not blindly retry. Renew the expiration before it passes, or delete the resource when no longer needed.
Errors
| 400 | Invalid fields, expiration, unsupported model, or insufficient cache content. |
| 401 / 403 | Authentication, model access, or content-retention permission denied. |
| 404 | Cache missing, expired, or not owned by this identity; model not found. |
| 409 | Concurrent update or cache unavailable for this operation. |
| 413 | Request body exceeds the allowed size. |
| 429 | Request limit or service capacity exceeded. |
| 501 | Explicit caching is disabled. |
| 502 / 503 | The cache operation could not be completed. Try again later. |
To retrieve settled creation and storage charges, use Get Cache Billing.