Gemini 原生格式
- 直接使用 Google Generative Language 原生结构
- 保留
contents、parts、generationConfig等原生字段 - 需要视频理解、长音频、原生 grounding 时优先用这条路
认证
所有接口均使用 Bearer Token 进行认证。
也兼容 x-goog-api-key。
获取 API Key：访问控制台 创建。
请求时在请求头中添加：
Authorization: Bearer YOUR_OAIRoute_KEYAll endpoints authenticate with a Bearer token.
x-goog-api-key is also accepted.
Get an API key: open the console and create one.
Add it to the request header:
Authorization: Bearer YOUR_OAIRoute_KEY请求参数
对话内容数组。与 OpenAI 的 messages 不同，角色只有 user 与 model。
取值 user 或 model。首轮通常省略。
内容片段数组，一个 part 可以是一段文本、一张图或一段音频。
文本片段。
内联二进制数据，含 mime_type 与 data（Base64）。
已上传文件的引用，含 mime_type 与 file_uri。
系统指令，结构与 contents 的一项相同。
采样温度。
核采样阈值。
每步采样的候选数量。
输出 token 上限。
停止序列。
设为 application/json 时要求输出 JSON。
配合上面的 JSON 输出，给出字段结构。
安全过滤等级设置，按类别分别指定阈值。
工具清单，支持 functionDeclarations、googleSearch、codeExecution。
The conversation content array. Unlike OpenAI's messages, the only roles are user and model.
Either user or model. Usually omitted on the first turn.
The array of content parts; one part can be a piece of text, an image, or an audio clip.
A text part.
Inline binary data, containing mime_type and data (Base64).
A reference to an uploaded file, containing mime_type and file_uri.
The system instruction; structured like one entry of contents.
Sampling temperature.
Nucleus sampling threshold.
The number of candidates sampled per step.
The output token limit.
Stop sequences.
Set to application/json to require JSON output.
Works with the JSON output above to specify the field structure.
Safety filter levels, set per category.
The tool list; supports functionDeclarations, googleSearch, and codeExecution.
响应
候选回复数组。
回复内容片段。
结束原因。STOP 正常结束，MAX_TOKENS 触达上限，SAFETY 被安全策略拦截。
输入 token 数。
输出 token 数。
两者之和。
The array of candidate replies.
The reply content parts.
Why generation ended. STOP is normal, MAX_TOKENS hit the limit, SAFETY means it was blocked by safety policy.
Input token count.
Output token count.
The sum of both.
与 OpenAI 结构的差异
| OpenAI | Gemini 原生 |
|---|---|
messages | contents |
role: assistant | role: model |
content 字符串 | parts 数组 |
temperature 在顶层 | 在 generationConfig 里 |
max_tokens | maxOutputTokens |
Gemini 的参数名是驼峰式（maxOutputTokens、topP），与 OpenAI 的下划线风格不同。从 OpenAI 迁过来时最容易在这里出错。
| OpenAI | Gemini native |
|---|---|
messages | contents |
role: assistant | role: model |
content string | parts array |
temperature at the top level | Inside generationConfig |
max_tokens | maxOutputTokens |
Gemini's parameter names are camelCase (maxOutputTokens, topP), unlike OpenAI's underscore style. This is the easiest place to go wrong when migrating from OpenAI.
支持的模型列表
以下模型均可通过本接口调用，清单由模型目录自动生成，实际可用范围以你的账号分组为准：
Google 系列
gemini-4-argon旗舰，多模态gemini-3.8-flash主力，速度快gemini-3.5-flash-lite轻量，批量任务gemini-3-pro-image图像生成 等
Google 图像 系列
gemini-3-pro-image旗舰，4K 输出与文字渲染强gemini-3.1-flash-image轻量，适合批量 等
Google 语音 系列
gemini-3.1-flash-tts-preview轻量语音合成，多语言 等
更多模型持续更新中…
GET /api/pricing。The models below can all be called through this endpoint. The list is generated from the model catalog; what your account group actually allows takes precedence:
Google 系列
gemini-4-argon旗舰，多模态gemini-3.8-flash主力，速度快gemini-3.5-flash-lite轻量，批量任务gemini-3-pro-image图像生成 等
Google 图像 系列
gemini-3-pro-image旗舰，4K 输出与文字渲染强gemini-3.1-flash-image轻量，适合批量 等
Google 语音 系列
gemini-3.1-flash-tts-preview轻量语音合成，多语言 等
更多模型持续更新中…
GET /api/pricing directly.错误码
For error response formats, status codes, and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.
使用示例
基础对话
Gemini 原生的消息字段叫 contents，角色用 user 与 model，正文放在 parts 数组里。生成参数统一收进 generationConfig。
多轮对话
历史轮次按顺序放进 contents，模型回复的角色写 model。同样不需要服务端保存会话。
系统提示词
Gemini 的系统提示走独立的 systemInstruction 字段，不放在 contents 里。
生成参数
temperature、maxOutputTokens、topP 都放在 generationConfig 下，不在顶层。
流式输出
路径换成 streamGenerateContent 并加 alt=sse，返回 SSE 事件流，每个事件是一段 JSON。
图片输入
图片作为 inline_data 或 file_data 放进 parts，和文字并列。
结构化输出
在 generationConfig 里设 responseMimeType 为 application/json，并用 responseSchema 约束字段，返回的 text 可以直接解析。
Basic chat
Gemini's native message field is called contents; roles are user and model, and the body goes in a parts array. Generation parameters are all collected under generationConfig.
Multi-turn chat
Put prior turns into contents in order, writing model as the role for model replies. As elsewhere, the server keeps no session.
System prompt
Gemini's system prompt uses a separate systemInstruction field; it doesn't go inside contents.
Generation parameters
temperature, maxOutputTokens, and topP all sit under generationConfig, not at the top level.
Streaming output
Switch the path to streamGenerateContent and add alt=sse to get an SSE event stream, where each event is a JSON chunk.
Image input
Images go into parts as inline_data or file_data, alongside text.
Structured output
Set responseMimeType to application/json in generationConfig and constrain fields with responseSchema; the returned text can be parsed directly.