Skip to main content
POST
BaseURL: The default BaseURL is https://direct.evolink.ai, which has better support for text models and long-lived connections. https://api.evolink.ai is the primary endpoint for multimodal services and serves as a fallback address for text models.
Explicit context caching: Create a cache from a long prefix you reuse (long documents, system instructions, tool definitions); later generation requests send only the cache name and the new question. Cached tokens are billed at the cache hit rate. A cache write fee and an hourly storage fee also apply; storage is charged upfront for the full lifetime and is not refunded.
Using a cache: Add "cachedContent": "<name>" to the generateContent or streamGenerateContent request body and put only the new question in contents. Requests that reference a cache cannot include systemInstruction, tools, or toolConfig, and must use the same model as the cache.

Authorizations

Authorization
string
header
required

All endpoints require Bearer Token authentication

Get an API Key:

Visit API Key Management to get your API Key.

Add this request header:

The Gemini native format is also accepted: the x-goog-api-key: YOUR_API_KEY header or the ?key=YOUR_API_KEY URL parameter.

Body

application/json
model
string
required

Model; either models/gemini-3.8-flash or gemini-3.8-flash is accepted. Supported: gemini-3.8-flash, gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash, gemini-3.5-flash-lite, gemini-3-flash-preview, gemini-3.1-flash-lite-preview, gemini-3.1-pro-preview, gemini-3.1-pro-preview-customtools, gemini-3-pro-preview

Example:

"models/gemini-3.8-flash"

contents
object[]

Conversation content to cache; must be an array. It becomes the conversation prefix when referencing the cache. Provide at least one of contents, systemInstruction, or tools

systemInstruction
object

System instructions. Once cached, systemInstruction must not be included in generation requests referencing this cache

tools
object[]

Tool declarations. Once cached, tools must not be included in generation requests referencing this cache

toolConfig
object

Tool calling configuration (such as functionCallingConfig). Once cached, toolConfig must not be included in generation requests referencing this cache

ttl
string

Lifetime, such as "3600s". Minimum 60s, maximum 604800s (168 hours). Mutually exclusive with expireTime; providing both returns 400. Defaults to 3600s when neither is provided

Example:

"3600s"

expireTime
string<date-time>

Absolute expiry time (RFC 3339, UTC), mutually exclusive with ttl; providing both returns 400

Example:

"2026-11-03T06:00:00Z"

displayName
string

A name for your reference, up to 255 characters; does not affect billing

Maximum string length: 255
Example:

"product-manual-v3"

Response

Cache created. usageMetadata.totalTokenCount is the cached token count used to calculate write and storage fees

name
string

Cache name, in the form cachedContents/<id>. Use it in the cachedContent field of generation requests; <id> is also the creation request's ID

Example:

"cachedContents/20261103012026348092000s1oTuB96"

model
string

Model bound to the cache; the generation request must use the same model

Example:

"models/gemini-3.8-flash"

displayName
string

Name provided on creation; omitted if not provided

createTime
string<date-time>

Creation time (UTC)

updateTime
string<date-time>

Most recent update time (UTC)

expireTime
string<date-time>

Expiry time (UTC); automatically deleted on expiry

usageMetadata
object