# Gemini 原生格式
> 直接使用 Google Generative Language 原生结构
> 保留 `contents`、`parts`、`generationConfig` 等原生字段
> 需要视频理解、长音频、原生 grounding 时优先用这条路
`POST /v1beta/models/gemini-2.5-pro:generateContent`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 也兼容 `x-goog-api-key`。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求参数
- `contents` (array / 必填) — 对话内容数组。与 OpenAI 的 messages 不同，角色只有 `user` 与 `model`。
- `contents[].role` (string / 可选) — 取值 `user` 或 `model`。首轮通常省略。
- `contents[].parts` (array / 必填) — 内容片段数组，一个 part 可以是一段文本、一张图或一段音频。
- `contents[].parts[].text` (string / 可选) — 文本片段。
- `contents[].parts[].inline_data` (object / 可选) — 内联二进制数据，含 `mime_type` 与 `data`（Base64）。
- `contents[].parts[].file_data` (object / 可选) — 已上传文件的引用，含 `mime_type` 与 `file_uri`。
- `system_instruction` (object / 可选) — 系统指令，结构与 `contents` 的一项相同。
- `generationConfig.temperature` (number / 可选) — 采样温度。
- `generationConfig.topP` (number / 可选) — 核采样阈值。
- `generationConfig.topK` (integer / 可选) — 每步采样的候选数量。
- `generationConfig.maxOutputTokens` (integer / 可选) — 输出 token 上限。
- `generationConfig.stopSequences` (array / 可选) — 停止序列。
- `generationConfig.responseMimeType` (string / 可选) — 设为 `application/json` 时要求输出 JSON。
- `generationConfig.responseSchema` (object / 可选) — 配合上面的 JSON 输出，给出字段结构。
- `safetySettings` (array / 可选) — 安全过滤等级设置，按类别分别指定阈值。
- `tools` (array / 可选) — 工具清单，支持 `functionDeclarations`、`googleSearch`、`codeExecution`。
## 响应
- `candidates` (array) — 候选回复数组。
- `candidates[].content.parts` (array) — 回复内容片段。
- `candidates[].finishReason` (string) — 结束原因。`STOP` 正常结束，`MAX_TOKENS` 触达上限，`SAFETY` 被安全策略拦截。
- `usageMetadata.promptTokenCount` (integer) — 输入 token 数。
- `usageMetadata.candidatesTokenCount` (integer) — 输出 token 数。
- `usageMetadata.totalTokenCount` (integer) — 两者之和。
## 与 OpenAI 结构的差异
| OpenAI | Gemini 原生 |
|---|---|
| `messages` | `contents` |
| `role: assistant` | `role: model` |
| `content` 字符串 | `parts` 数组 |
| `temperature` 在顶层 | 在 `generationConfig` 里 |
| `max_tokens` | `maxOutputTokens` |
> **Note:** 
> Gemini 的参数名是驼峰式（`maxOutputTokens`、`topP`），与 OpenAI 的下划线风格不同。从 OpenAI 迁过来时最容易在这里出错。
## 支持的模型列表
以下模型均可通过本接口调用，清单由模型目录自动生成，实际可用范围以你的账号分组为准：
:::models google
> **Note:** 想按上下文长度、价格或能力标签挑选模型，可查阅 [模型列表元数据接口](../models.html)，或直接读取 `GET /api/pricing`。
## 错误码
错误响应的格式、状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 使用示例
### 基础对话
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}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      { "role": "user", "parts": [{ "text": "用一句话说明什么是 CDN" }] }
    ]
  }'
```
**基础对话{Basic chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [
      { "role": "user", "parts": [{ "text": "用一句话说明什么是 CDN" }] }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**基础对话{Basic chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [
      { "role": "user", "parts": [{ "text": "用一句话说明什么是 CDN" }] }
    ]
  }),
});
console.log(await res.json());
```
**多轮对话{Multi-turn chat}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      { "role": "user", "parts": [{ "text": "我们的日活是三万，缓存该怎么分层" }] },
      { "role": "model", "parts": [{ "text": "先分本地缓存和分布式缓存两层，热点数据放本地。" }] },
      { "role": "user", "parts": [{ "text": "本地缓存怎么保证一致性" }] }
    ]
  }'
```
**多轮对话{Multi-turn chat}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [
      { "role": "user", "parts": [{ "text": "我们的日活是三万，缓存该怎么分层" }] },
      { "role": "model", "parts": [{ "text": "先分本地缓存和分布式缓存两层，热点数据放本地。" }] },
      { "role": "user", "parts": [{ "text": "本地缓存怎么保证一致性" }] }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**多轮对话{Multi-turn chat}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [
      { "role": "user", "parts": [{ "text": "我们的日活是三万，缓存该怎么分层" }] },
      { "role": "model", "parts": [{ "text": "先分本地缓存和分布式缓存两层，热点数据放本地。" }] },
      { "role": "user", "parts": [{ "text": "本地缓存怎么保证一致性" }] }
    ]
  }),
});
console.log(await res.json());
```
**系统提示词{System prompt}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "systemInstruction": {
      "parts": [{ "text": "你是运维助手，只给结论和命令，不解释原理。" }]
    },
    "contents": [
      { "role": "user", "parts": [{ "text": "怎么查看某个端口被谁占用" }] }
    ]
  }'
```
**系统提示词{System prompt}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "systemInstruction": {
      "parts": [{ "text": "你是运维助手，只给结论和命令，不解释原理。" }]
    },
    "contents": [
      { "role": "user", "parts": [{ "text": "怎么查看某个端口被谁占用" }] }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**系统提示词{System prompt}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "systemInstruction": {
      "parts": [{ "text": "你是运维助手，只给结论和命令，不解释原理。" }]
    },
    "contents": [
      { "role": "user", "parts": [{ "text": "怎么查看某个端口被谁占用" }] }
    ]
  }),
});
console.log(await res.json());
```
**生成参数{Generation parameters}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      { "role": "user", "parts": [{ "text": "给一个不超过二十字的团队口号" }] }
    ],
    "generationConfig": {
      "temperature": 0.9,
      "maxOutputTokens": 64,
      "topP": 0.95
    }
  }'
```
**生成参数{Generation parameters}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [
      { "role": "user", "parts": [{ "text": "给一个不超过二十字的团队口号" }] }
    ],
    "generationConfig": {
      "temperature": 0.9,
      "maxOutputTokens": 64,
      "topP": 0.95
    }
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**生成参数{Generation parameters}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [
      { "role": "user", "parts": [{ "text": "给一个不超过二十字的团队口号" }] }
    ],
    "generationConfig": {
      "temperature": 0.9,
      "maxOutputTokens": 64,
      "topP": 0.95
    }
  }),
});
console.log(await res.json());
```
**流式输出{Streaming output}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [
      { "role": "user", "parts": [{ "text": "分三点讲讲微服务拆分的原则" }] }
    ]
  }'
```
**流式输出{Streaming output}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [
      { "role": "user", "parts": [{ "text": "分三点讲讲微服务拆分的原则" }] }
    ]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**流式输出{Streaming output}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [
      { "role": "user", "parts": [{ "text": "分三点讲讲微服务拆分的原则" }] }
    ]
  }),
});
console.log(await res.json());
```
**图片输入{Image input}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "这张图里的报错是什么原因" },
        { "inline_data": { "mime_type": "image/png", "data": "iVBORw0KGgo..." } }
      ]
    }]
  }'
```
**图片输入{Image input}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "这张图里的报错是什么原因" },
        { "inline_data": { "mime_type": "image/png", "data": "iVBORw0KGgo..." } }
      ]
    }]
  }
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**图片输入{Image input}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "这张图里的报错是什么原因" },
        { "inline_data": { "mime_type": "image/png", "data": "iVBORw0KGgo..." } }
      ]
    }]
  }),
});
console.log(await res.json());
```
**200 基础对话{Basic chat}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "CDN 是把内容缓存到离用户最近的节点，从而加快访问速度的分发网络。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 26,
    "totalTokenCount": 38
  },
  "modelVersion": "gemini-2.5-pro"
}
```
**200 多轮对话{Multi-turn chat}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "可以设置较短的过期时间，并在数据更新时通过消息通知各节点失效本地缓存。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 58,
    "candidatesTokenCount": 34,
    "totalTokenCount": 92
  },
  "modelVersion": "gemini-2.5-pro"
}
```
**200 系统提示词{System prompt}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "lsof -i :8080\n或\nss -lntp | grep 8080"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 31,
    "candidatesTokenCount": 18,
    "totalTokenCount": 49
  },
  "modelVersion": "gemini-2.5-pro"
}
```
**200 生成参数{Generation parameters}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "一起出发，一起抵达。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 17,
    "candidatesTokenCount": 7,
    "totalTokenCount": 24
  },
  "modelVersion": "gemini-2.5-pro"
}
```
**200 流式输出{Streaming output}**
```
data: {"candidates": [{"content": {"role": "model", "parts": [{"text": "一、按业务边界拆分；"}]}, "index": 0}]}
data: {"candidates": [{"content": {"role": "model", "parts": [{"text": "二、每个服务独立存储数据；"}]}, "index": 0}]}
data: {"candidates": [{"content": {"role": "model", "parts": [{"text": "三、服务之间只通过接口通信。"}]}, "finishReason": "STOP", "index": 0}], "usageMetadata": {"promptTokenCount": 14, "candidatesTokenCount": 38, "totalTokenCount": 52}, "modelVersion": "gemini-2.5-pro"}
```
**200 图片输入{Image input}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "报错是连接被拒绝，说明目标端口没有服务在监听，请检查服务是否已启动。"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 282,
    "candidatesTokenCount": 29,
    "totalTokenCount": 311
  },
  "modelVersion": "gemini-2.5-pro"
}
```
**结构化输出{Structured output}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "contents": [{ "role": "user", "parts": [{ "text": "把这句话抽取成 JSON：我叫李明，住在杭州。" }] }],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "object",
        "properties": { "name": { "type": "string" }, "city": { "type": "string" } }
      }
    }
  }'
```
**结构化输出{Structured output}::Python**
```
import requests
url = "https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent"
headers = {"Authorization": "Bearer YOUR_OAIRoute_KEY"}
payload = {
  "contents": [{ "role": "user", "parts": [{ "text": "把这句话抽取成 JSON：我叫李明，住在杭州。" }] }],
  "generationConfig": {
    "responseMimeType": "application/json",
    "responseSchema": {
      "type": "object",
      "properties": { "name": { "type": "string" }, "city": { "type": "string" } }
    }
  }
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**结构化输出{Structured output}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "contents": [{ "role": "user", "parts": [{ "text": "把这句话抽取成 JSON：我叫李明，住在杭州。" }] }],
    "generationConfig": {
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "object",
        "properties": { "name": { "type": "string" }, "city": { "type": "string" } }
      }
    }
  }),
});
console.log(await res.json());
```
**200 结构化输出{Structured output}**
```
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "{\"name\": \"李明\", \"city\": \"杭州\"}"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 14,
    "totalTokenCount": 38
  },
  "modelVersion": "gemini-2.5-pro"
}
```