跳转到主要内容
POST
BaseURL 说明:默认 BaseURL 为 https://direct.evolink.ai,对文本模型支持更好,支持长连接;https://api.evolink.ai 是多模态主力地址,对文本模型作为备用地址使用。
显式上下文缓存:把反复使用的长前缀(长文档、系统指令、工具定义)创建为缓存,之后的生成请求只带缓存名和新问题。命中部分按缓存命中单价计费;另收缓存写入费和按时长计的存储费,存储费在创建时按有效期一次收取,不退。
引用缓存:在 generateContent 或 streamGenerateContent 的请求体中加入 "cachedContent": "<name>",contents 只放新问题。引用缓存的请求不能再携带 systemInstruction、tools、toolConfig,模型需与创建缓存时一致。

授权

Authorization
string
header
必填

##所有接口均需要使用 Bearer Token 进行认证##

获取 API Key:

访问 API Key 管理页面 获取您的 API Key

使用时在请求头中添加:

也接受 Gemini 原生写法:请求头 x-goog-api-key: YOUR_API_KEY,或 URL 参数 ?key=YOUR_API_KEY。

请求体

application/json
model
string
必填

模型,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"

contents
object[]

要缓存的对话内容,必须是数组。引用缓存时这些内容会作为对话前缀。contents、systemInstruction、tools 至少提供一项

systemInstruction
object

系统指令。写进缓存后,引用缓存的生成请求里不能再带 systemInstruction

tools
object[]

工具声明。写进缓存后,引用缓存的生成请求里不能再带 tools

toolConfig
object

工具调用配置(如 functionCallingConfig)。写进缓存后,引用缓存的生成请求里不能再带 toolConfig

ttl
string

有效期,如 "3600s"。最短 60s,最长 604800s(168 小时)。与 expireTime 二选一,同时传入返回 400;都不填默认 3600s

示例:

"3600s"

expireTime
string<date-time>

绝对到期时间(RFC 3339,UTC),与 ttl 二选一,同时传入返回 400

示例:

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

displayName
string

给自己看的名字,最长 255 个字符,不影响计费

Maximum string length: 255
示例:

"product-manual-v3"

响应

缓存已创建。usageMetadata.totalTokenCount 是缓存的 token 数,写入费与存储费都按它计算

name
string

缓存名,形如 cachedContents/<id>。生成请求的 cachedContent 字段填它;<id> 同时是创建请求的请求号

示例:

"cachedContents/20261103012026348092000s1oTuB96"

model
string

缓存绑定的模型,引用时生成请求的模型必须与之一致

示例:

"models/gemini-3.8-flash"

displayName
string

创建时给的名字,没给则不返回

createTime
string<date-time>

创建时间(UTC)

updateTime
string<date-time>

最近一次更新时间(UTC)

expireTime
string<date-time>

到期时间(UTC),到期后自动删除

usageMetadata
object