curl --request PATCH \
--url https://direct.evolink.ai/v1beta/cachedContents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"ttl": "7200s"
}'{
"name": "cachedContents/20261103012026348092000s1oTuB96",
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"createTime": "2026-11-03T01:20:27.311Z",
"updateTime": "2026-11-03T01:35:10.020Z",
"expireTime": "2026-11-03T03:35:10.000Z",
"usageMetadata": {
"totalTokenCount": 7525
}
}{
"error": {
"code": 400,
"message": "new expiry must be at least 60s in the future",
"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 extension",
"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": "cached content not found",
"status": "NOT_FOUND",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_NOT_FOUND",
"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": "cached content is temporarily unavailable; please retry later",
"status": "UNAVAILABLE",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_CHANNEL_UNAVAILABLE",
"domain": "evolink.ai"
}
]
}
}显式上下文缓存
Gemini 显式上下文缓存 - 延长或缩短有效期
只能改有效期,不能改内容。请求体给 ttl(从现在起算的新有效期,如 "7200s")或 expireTime(新的绝对到期时间)之一。
- 新到期时间距现在最短 60 秒、最长 168 小时。
- 只接受
ttl或expireTime;两者同时传入、或传入其它字段,返回 400。 - 延长:按新增时长补收存储费(按秒计,不足 1 秒按 1 秒)。缩短:不退已收的存储费。
- 这是付费操作:Key 需要有该模型的使用权限,按该 Key 当前所在用户组的价格计费,余额不足返回 402。
- 同一条延长请求重试时可带
Idempotency-Key请求头,避免重复扣费。
PATCH
/
v1beta
/
cachedContents
/
{id}
curl --request PATCH \
--url https://direct.evolink.ai/v1beta/cachedContents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"ttl": "7200s"
}'{
"name": "cachedContents/20261103012026348092000s1oTuB96",
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"createTime": "2026-11-03T01:20:27.311Z",
"updateTime": "2026-11-03T01:35:10.020Z",
"expireTime": "2026-11-03T03:35:10.000Z",
"usageMetadata": {
"totalTokenCount": 7525
}
}{
"error": {
"code": 400,
"message": "new expiry must be at least 60s in the future",
"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 extension",
"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": "cached content not found",
"status": "NOT_FOUND",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_NOT_FOUND",
"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": "cached content is temporarily unavailable; please retry later",
"status": "UNAVAILABLE",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "CACHE_CHANNEL_UNAVAILABLE",
"domain": "evolink.ai"
}
]
}
}BaseURL 说明:默认 BaseURL 为
https://direct.evolink.ai,对文本模型支持更好,支持长连接;https://api.evolink.ai 是多模态主力地址,对文本模型作为备用地址使用。只能修改有效期,请求体传
ttl 或 expireTime 之一。延长按新增时长补收存储费,缩短不退费。授权
##所有接口均需要使用 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
响应
更新后的缓存元数据,expireTime 为新的到期时间