curl --request POST \
--url https://direct.evolink.ai/v1beta/cachedContents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"systemInstruction": {
"parts": [
{
"text": "你是产品手册助手,只依据给定的手册内容回答,手册里没有的信息回答“手册未提及”。"
}
]
},
"contents": [
{
"role": "user",
"parts": [
{
"text": "(这里放产品手册全文。缓存内容需不少于 4,096 token。)"
}
]
}
],
"ttl": "3600s"
}
'{
"name": "cachedContents/20261103012026348092000s1oTuB96",
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"createTime": "2026-11-03T01:20:27.311Z",
"updateTime": "2026-11-03T01:20:27.311Z",
"expireTime": "2026-11-03T02:20:26.902Z",
"usageMetadata": {
"totalTokenCount": 7525
}
}{
"error": {
"code": 400,
"message": "ttl must not exceed 604800s (168h)",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 401,
"message": "Invalid API key",
"status": "UNAUTHENTICATED"
}
}{
"error": {
"code": 402,
"message": "insufficient quota for cache storage prepayment",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INSUFFICIENT_QUOTA",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 403,
"message": "This key is not allowed to use model gemini-3.8-flash",
"status": "PERMISSION_DENIED"
}
}{
"error": {
"code": 404,
"message": "explicit context caching is not enabled",
"status": "NOT_FOUND",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "EXPLICIT_CACHE_DISABLED",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 413,
"message": "cache content exceeds 10485760 bytes; reference large files with fileData.fileUri instead",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_CONTENT_TOO_LARGE",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded",
"status": "RESOURCE_EXHAUSTED"
}
}{
"error": {
"code": 502,
"message": "the request could not be completed due to a service authorization problem; please retry later or contact support",
"status": "INTERNAL",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "UPSTREAM_ERROR",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 503,
"message": "explicit context caching is temporarily unavailable",
"status": "UNAVAILABLE",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INTERNAL",
"domain": "evolink.ai"
}
]
}
}显式上下文缓存
Gemini 显式上下文缓存 - 创建缓存
把 contents、systemInstruction、tools(至少一项,可另带 toolConfig)创建为一份缓存,返回缓存名 name。
- 模型:
model写models/gemini-3.8-flash或gemini-3.8-flash都可以。支持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;Gemini 4 系列不支持显式缓存。 - 有效期:
ttl形如"3600s",或expireTime(RFC 3339 时间),两者只能给一个;都不填默认 1 小时。最短 60 秒,最长 168 小时(604800s),到期自动删除。 - 大小:请求体不超过 10 MB;缓存内容需达到模型要求的最小 token 数(如
gemini-3.8-flash为 4,096 token),不足返回 400。 - 字段:只接受本接口列出的字段,传入其它字段返回 400。
- tools:只接受
googleSearch、codeExecution、functionDeclarations,其它工具返回 400。 - 返回的
name:形如cachedContents/<id>,<id>就是本次请求的请求 ID。在控制台「日志」页按这个 id 搜索,就能看到创建缓存的扣费记录。 - 计费:创建时收取「缓存写入费」(单价与输入相同),并按有效期一次收取「缓存存储费」(每百万 token 每小时);引用缓存时,命中部分按缓存命中单价计费,缓存中声明了
googleSearch时每次搜索另计。缩短、删除、到期都不退存储费;延长按新增时长补收。各模型单价见 价格页。
认证使用 Authorization: Bearer,也接受 x-goog-api-key 请求头。
POST
/
v1beta
/
cachedContents
curl --request POST \
--url https://direct.evolink.ai/v1beta/cachedContents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"systemInstruction": {
"parts": [
{
"text": "你是产品手册助手,只依据给定的手册内容回答,手册里没有的信息回答“手册未提及”。"
}
]
},
"contents": [
{
"role": "user",
"parts": [
{
"text": "(这里放产品手册全文。缓存内容需不少于 4,096 token。)"
}
]
}
],
"ttl": "3600s"
}
'{
"name": "cachedContents/20261103012026348092000s1oTuB96",
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"createTime": "2026-11-03T01:20:27.311Z",
"updateTime": "2026-11-03T01:20:27.311Z",
"expireTime": "2026-11-03T02:20:26.902Z",
"usageMetadata": {
"totalTokenCount": 7525
}
}{
"error": {
"code": 400,
"message": "ttl must not exceed 604800s (168h)",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INVALID_ARGUMENT",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 401,
"message": "Invalid API key",
"status": "UNAUTHENTICATED"
}
}{
"error": {
"code": 402,
"message": "insufficient quota for cache storage prepayment",
"status": "RESOURCE_EXHAUSTED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INSUFFICIENT_QUOTA",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 403,
"message": "This key is not allowed to use model gemini-3.8-flash",
"status": "PERMISSION_DENIED"
}
}{
"error": {
"code": 404,
"message": "explicit context caching is not enabled",
"status": "NOT_FOUND",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "EXPLICIT_CACHE_DISABLED",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 413,
"message": "cache content exceeds 10485760 bytes; reference large files with fileData.fileUri instead",
"status": "INVALID_ARGUMENT",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_CONTENT_TOO_LARGE",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded",
"status": "RESOURCE_EXHAUSTED"
}
}{
"error": {
"code": 502,
"message": "the request could not be completed due to a service authorization problem; please retry later or contact support",
"status": "INTERNAL",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "UPSTREAM_ERROR",
"domain": "evolink.ai"
}
]
}
}{
"error": {
"code": 503,
"message": "explicit context caching is temporarily unavailable",
"status": "UNAVAILABLE",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "INTERNAL",
"domain": "evolink.ai"
}
]
}
}BaseURL 说明:默认 BaseURL 为
https://direct.evolink.ai,对文本模型支持更好,支持长连接;https://api.evolink.ai 是多模态主力地址,对文本模型作为备用地址使用。显式上下文缓存:把反复使用的长前缀(长文档、系统指令、工具定义)创建为缓存,之后的生成请求只带缓存名和新问题。命中部分按缓存命中单价计费;另收缓存写入费和按时长计的存储费,存储费在创建时按有效期一次收取,不退。
引用缓存:在
generateContent 或 streamGenerateContent 的请求体中加入 "cachedContent": "<name>",contents 只放新问题。引用缓存的请求不能再携带 systemInstruction、tools、toolConfig,模型需与创建缓存时一致。授权
##所有接口均需要使用 Bearer Token 进行认证##
获取 API Key:
访问 API Key 管理页面 获取您的 API Key
使用时在请求头中添加:
Authorization: Bearer YOUR_API_KEY
也接受 Gemini 原生写法:请求头 x-goog-api-key: YOUR_API_KEY,或 URL 参数 ?key=YOUR_API_KEY。
请求体
application/json
模型,models/gemini-3.8-flash 或 gemini-3.8-flash 两种写法均可。支持 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
示例:
"models/gemini-3.8-flash"
响应
缓存已创建。usageMetadata.totalTokenCount 是缓存的 token 数,写入费与存储费都按它计算