API 示例API REFERENCE

Gemini 原生 API

Gemini 原生 API 统一使用 /v1/models/{model}:... 路径，保留 Gemini 请求和响应语义。

统一 API Endpointhttps://api.tokensapi.cnPOST /v1/models/{model}:generateContent

认证方式Bearer API Key

响应协议JSON / SSE

调用入口统一网关

请求接口

请求地址固定，请根据当前页面的参数说明替换模型 ID 和业务输入。

POST${base_url}/v1/models/{model}:generateContent

POST${base_url}/v1/models/{model}:streamGenerateContent

POST${base_url}/v1/models/{model}:embedContent

POST${base_url}/v1/models/{model}:batchEmbedContents

鉴权

选择一种 Gemini-compatible 鉴权方式。

参数	类型	必填	默认值	说明
`Authorization`	`string`	否	—	Bearer API Key。
`x-goog-api-key`	`string`	否	—	Gemini API Key Header。
`key`	`string`	否	—	URL 查询参数 ?key=<API_KEY>。

Generate Content / Stream Generate Content

两个生成端点都使用 contents；Stream Generate Content 开启原生 SSE，且支持 Session 路由。

参数	类型	必填	默认值	说明
`contents`	`Content[]`	是	—	非空 Gemini content/part 数组。
`systemInstruction`	`Content`	否	—	系统内容。
`generationConfig`	`object`	否	—	生成配置。
`tools`	`array`	否	—	工具声明。
`session_id / extra_body.session_id / X-Session-Id`	`string`	否	—	生成接口的 Session 路由，按该优先级读取。可选值 / 约束：最长 256 个字符。
`extra_body.provider`	`object`	否	—	可选 provider 路由配置。

Embed Content

Embed Content 使用单个 content，不展示 Session 路由。

参数	类型	必填	默认值	说明
`content`	`Content`	是	—	待嵌入的单个 Gemini Content。
`taskType`	`string`	否	—	模型支持时的嵌入任务类型。
`outputDimensionality`	`integer`	否	—	模型支持时的输出维度。
`extra_body.provider`	`object`	否	—	可选 provider 路由配置。

Batch Embed Contents

requests[] 必须非空。URL 中的 model 会同时写入根请求和每一个子请求。

参数	类型	必填	默认值	说明
`requests[]`	`EmbedContentRequest[]`	是	—	非空的嵌入子请求数组。
`requests[].content`	`Content`	是	—	每个子请求的嵌入内容。
`extra_body.provider`	`object`	否	—	可选 provider 路由配置。

响应 Header

以下字段属于 HTTP 响应 Header，不属于 JSON、SSE 事件或二进制响应 body。网络层失败而未进入网关时不保证返回。

参数	类型	必填	默认值	说明
`X-Client-Request-Id`	`string`	否	—	调用方在请求中提供时回显；未提供时网关不会自动生成。
`X-Upstream-Request-Id`	`string`	否	—	通常用于网关请求追踪，不代表 provider 的原始 request ID。

错误响应

错误 body 遵循所选协议。HTTP 400 表示 invalid_request，HTTP 402 表示可用余额或配额不足，HTTP 429 表示限流。

参数	类型	必填	默认值	说明
`error.code`	`string`	否	—	协议定义的机器可读错误码。
`error.message`	`string`	否	—	可读错误说明。

流式完成

Gemini 原生流在最后一个带 finishReason 和 usageMetadata 的响应后结束，不追加 data: [DONE]。客户端按 candidate 和 part 聚合内容，并将异常 EOF 视为未完成。

嵌入响应

embedContent 返回 embedding.values，batchEmbedContents 返回 embeddings[]；两种嵌入接口均不流式。

调用示例

示例使用占位符，请替换为模型详情页中当前可用的 model ID，并将 API Key 保存在服务端环境变量中。

curl -X POST "https://api.tokensapi.cn/v1/models/<MODEL_ID>:generateContent" \
  -H "x-goog-api-key: $TOKEN_MARKET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Explain caching."}]}],"extra_body":{"session_id":"conversation-<UUID>","provider":{"sort":["latency"]}}}'

本页是否有帮助？

音频（Audio）

实时接口（Realtime）

参数

类型

必填

默认值

说明

Authorization

string

否

—

Bearer API Key。

x-goog-api-key

string

否

—

Gemini API Key Header。

key

string

否

—

URL 查询参数 ?key=<API_KEY>。

参数

类型

必填

默认值

说明

contents

Content[]

是

—

非空 Gemini content/part 数组。

systemInstruction

Content

否

—

系统内容。

generationConfig

object

否

—

生成配置。

tools

array

否

—

工具声明。

session_id / extra_body.session_id / X-Session-Id

string

否

—

生成接口的 Session 路由，按该优先级读取。

可选值 / 约束：最长 256 个字符。

extra_body.provider

object

否

—

可选 provider 路由配置。

参数

类型

必填

默认值

说明

content

Content

是

—

待嵌入的单个 Gemini Content。

taskType

string

否

—

模型支持时的嵌入任务类型。

outputDimensionality

integer

否

—

模型支持时的输出维度。

extra_body.provider

object

否

—

可选 provider 路由配置。

参数

类型

必填

默认值

说明

requests[]

EmbedContentRequest[]

是

—

非空的嵌入子请求数组。

requests[].content

Content

是

—

每个子请求的嵌入内容。

extra_body.provider

object

否

—

可选 provider 路由配置。

参数

类型

必填

默认值

说明

X-Client-Request-Id

string

否

—

调用方在请求中提供时回显；未提供时网关不会自动生成。

X-Upstream-Request-Id

string

否

—

通常用于网关请求追踪，不代表 provider 的原始 request ID。

参数

类型

必填

默认值

说明

error.code

string

否

—

协议定义的机器可读错误码。

error.message

string

否

—

可读错误说明。

curl -X POST "https://api.tokensapi.cn/v1/models/<MODEL_ID>:generateContent" \ -H "x-goog-api-key: $TOKEN_MARKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"contents":[{"role":"user","parts":[{"text":"Explain caching."}]}],"extra_body":{"session_id":"conversation-<UUID>","provider":{"sort":["latency"]}}}'