Gemini 文本聊天

POST /v1beta/models/{model}:generateContent

代理 Gemini API 请求。普通请求使用 /v1beta/models/{model_name}:generateContent，流式请求使用 /v1beta/models/{model_name}:streamGenerateContent?alt=sse。

请求参数

路径参数

模型路径参数

参数	类型	默认值	说明	是否必填
`model`	string	—	模型名称，位于 `/v1beta/models/{model}` 路径中。	是

请求头

x-goog-api-key

使用 Gemini API Key 认证。

格式: x-goog-api-key: sk-xxxxxx

请求体

顶层字段（5 个）

参数	类型	默认值	说明	是否必填
`contents`	array	—	按时间顺序排列的消息。每项包含 `role`（`user` 或 `model`）和 `parts`。	否
`generationConfig`	object	—	生成控制参数，如温度、Top-P 和最大输出 token 数。	否
`safetySettings`	array	—	按安全类别覆盖默认安全阈值。	否
`tools`	array	—	声明模型可调用的工具；可用形式由模型决定。	否
`systemInstruction`	object	—	系统级指令，通常包含 `parts` 数组。	否

网关会把空请求转发给上游，但实际模型通常要求至少一条 contents 消息。

contents[] 与生成参数

参数	类型	默认值	说明	是否必填
`contents[].role`	string	—	`user` 表示用户输入，`model` 表示历史模型输出。	否
`contents[].parts`	array	—	内容片段数组。文本片段使用 `{ "text": "..." }`；媒体片段请参阅[媒体识别](../media/README.md)。	条件
`generationConfig.temperature`	number	—	采样温度，取值范围和默认值由模型决定。	否
`generationConfig.topP`	number	—	核采样阈值。	否
`generationConfig.topK`	integer	—	候选 token 数量。	否
`generationConfig.maxOutputTokens`	integer	—	限制本次响应最多生成的 token 数。	否
`generationConfig.stopSequences`	array<string>	—	命中任一序列后停止生成。	否
`safetySettings[].category`	string	—	安全类别，例如 `HARM_CATEGORY_HARASSMENT`。	条件
`safetySettings[].threshold`	string	—	该类别的拦截阈值，例如 `BLOCK_MEDIUM_AND_ABOVE`。	条件

请求体示例

查看 JSON 请求体示例

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "用三句话介绍新加坡。" }]
    }
  ],
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.95,
    "maxOutputTokens": 256
  },
  "systemInstruction": {
    "parts": [{ "text": "回答要简洁、准确。" }]
  }
}

请求示例代码

cURLJavaScriptGoPythonJavaC#

curl -X POST "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{"contents":[{"role":"user","parts":[{"text":"用三句话介绍新加坡。"}]}],"generationConfig":{"maxOutputTokens":256}}'

const payload = {
  contents: [{ role: "user", parts: [{ text: "用三句话介绍新加坡。" }] }],
  generationConfig: { maxOutputTokens: 256 }
};
const response = await fetch("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", {
  method: "POST",
  headers: { "x-goog-api-key": process.env.GEMINI_API_KEY },
  body: JSON.stringify(payload)
});
console.log(await response.json());

payload := `{"contents":[{"role":"user","parts":[{"text":"用三句话介绍新加坡。"}]}],"generationConfig":{"maxOutputTokens":256}}`
req, _ := http.NewRequest("POST", "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", strings.NewReader(payload))
req.Header.Set("x-goog-api-key", os.Getenv("GEMINI_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer res.Body.Close()

import os
import requests

payload = {"contents": [{"role": "user", "parts": [{"text": "用三句话介绍新加坡。"}]}], "generationConfig": {"maxOutputTokens": 256}}
response = requests.post(
    "https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent",
    json=payload,
)
print(response.json())

var client = java.net.http.HttpClient.newHttpClient();
var payload = "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"用三句话介绍新加坡。\"}]}],\"generationConfig\":{\"maxOutputTokens\":256}}";
var request = java.net.http.HttpRequest.newBuilder()
    .uri(java.net.URI.create("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent"))
    .header("x-goog-api-key", System.getenv("GEMINI_API_KEY"))
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(payload)).build();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

using System.Net.Http.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-goog-api-key", Environment.GetEnvironmentVariable("GEMINI_API_KEY"));
var payload = new { contents = new[] { new { role = "user", parts = new[] { new { text = "用三句话介绍新加坡。" } } } }, generationConfig = new { maxOutputTokens = 256 } };
var response = await client.PostAsJsonAsync("https://10000router.com/v1beta/models/gemini-2.5-pro:generateContent", payload);
Console.WriteLine(await response.Content.ReadAsStringAsync());

返回响应

响应示例

{
  "candidates": [{
    "content": { "role": "model", "parts": [{ "text": "新加坡是一个现代化城市国家。" }] },
    "finishReason": "STOP",
    "safetyRatings": []
  }],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "totalTokenCount": 30
  }
}

返回字段

顶层字段（2 个）

字段	类型	说明
`candidates`	array	模型生成的候选结果。
`usageMetadata`	object	输入、输出和总 token 数。

candidates[]

字段	类型	说明
`content.role`	string	通常为 `model`。
`content.parts`	array	响应内容片段，文本位于 `parts[].text`。
`finishReason`	string	生成结束原因，例如 `STOP`、`MAX_TOKENS` 或安全拦截原因。
`safetyRatings`	array	安全分类和概率评估。

usageMetadata

字段	类型	说明
`promptTokenCount`	integer	输入 token 数。
`candidatesTokenCount`	integer	候选输出 token 数。
`totalTokenCount`	integer	输入与输出 token 总数。

流式响应

将路径中的动作替换为 :streamGenerateContent 并附加 ?alt=sse，即使用 /v1beta/models/{model}:streamGenerateContent?alt=sse 作为流式请求路径。

流式请求返回 text/event-stream。每个 data 事件包含一个 Gemini 响应片段；客户端应按顺序拼接 candidates[].content.parts[].text，直到收到 finishReason。与 OpenAI SSE 不同，Gemini 流通常不发送 [DONE] 标记。

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"新加坡"}]},"finishReason":""}]}

data: {"candidates":[{"content":{"parts":[{"text":"是一个城市国家。"}]},"finishReason":"STOP"}]}

文本聊天