Create explicit cache

POST/v1/cachedContents

Create 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

modelstringrequired

Model 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.

systemInstructionobject

System instruction to cache, using Gemini Content format.

toolsobject[]

Gemini tool definitions to cache, subject to model support.

tools.typestring

Tool type, usually function.

tools.functionobject

Function definition.

toolConfigobject

Gemini tool configuration to cache, subject to model support.

displayNamestring

Optional human-readable label.

ttlstring

Lifetime 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.

expireTimestring

Future 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

namestring

Cache resource name: cachedContents/{id}. Save it for subsequent operations.

modelstring

Model name in models/{model} form.

displayNamestring

Display label, when returned.

createTimestring

Creation timestamp (RFC3339), when returned.

updateTimestring

Last update timestamp (RFC3339), when returned.

expireTimestring

Expiration timestamp (RFC3339), when returned.

usageMetadataobject

Cache usage information, when returned.

usageMetadata.totalTokenCountinteger

Number 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.

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 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

400Invalid fields, expiration, unsupported model, or insufficient cache content.
401 / 403Authentication, model access, or content-retention permission denied.
404Cache missing, expired, or not owned by this identity; model not found.
409Concurrent update or cache unavailable for this operation.
413Request body exceeds the allowed size.
429Request limit or service capacity exceeded.
501Explicit caching is disabled.
502 / 503The cache operation could not be completed. Try again later.

To retrieve settled creation and storage charges, use Get Cache Billing.

Solicitar

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 @-

Respuesta

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}
¿Ha sido de ayuda?
Create explicit cache · Token360