Gemini API
鉴权方式:Authorization: Bearer <YOUR_API_KEY>。
外部 URL 可以是公开 HTTPS URL 或签名 URL。每个请求或载荷最多处理 100 MB 的外部文件,处理期间需保持 URL 可访问。
详见 Gemini 文件输入说明。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model(路径) | string | 是 | /v1beta/models/{model}:generateContent 中的模型 ID。 |
contents | array | 是 | 对话内容列表。每项包含 parts,文本内容使用 {“text”:”…”}。多轮对话需包含此前的用户与模型消息。 |
systemInstruction | object | 否 | 系统指令,使用包含文本内容的 parts 数组。 |
generationConfig.temperature | number | 否 | 控制输出随机性,取值范围为 0.0 至 2.0;默认值因模型而异。Gemini 3.6 Flash 及更新模型会忽略此字段。 |
generationConfig.topP | number | 否 | 核采样阈值。 |
generationConfig.topK | number | 否 | 将候选范围限制为概率最高的 Token。 |
generationConfig.maxOutputTokens | integer | 否 | 输出最大 Token 数,具体上限因模型而异。 |
generationConfig.candidateCount | integer | 否 | 返回的候选响应数量,默认为 1。 |
generationConfig.stopSequences | string[] | 否 | 遇到指定字符串时停止生成。 |
generationConfig.responseMimeType | string | 否 | 响应 MIME 类型;结构化 JSON 输出可使用 application/json。 |
generationConfig.responseSchema | object | 否 | 结构化 JSON 输出的 Schema,需与 responseMimeType: “application/json” 配合使用。Gemini API 已将此字段标记为弃用。 |
generationConfig.thinkingConfig | object | 否 | 思考选项,例如 thinkingLevel、thinkingBudget 或 includeThoughts,支持情况因模型而异。 |
tools | array | 否 | 工具定义,可包含函数声明或模型支持的内置工具。 |
toolConfig.functionCallingConfig | object | 否 | 函数调用模式(AUTO、ANY 或 NONE),也可限定允许调用的函数名称。 |
safetySettings | array | 否 | 设置请求的安全类别和拦截阈值。 |
cachedContent | string | 否 | 作为上下文使用的缓存内容名称。 |
调用示例
cURL
curl "https://api.example.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"systemInstruction": {
"parts": [{"text": "请清晰、简洁地回答。"}]
},
"contents": [
{
"role": "user",
"parts": [{"text": "用一句话说明 API 的作用。"}]
}
],
"generationConfig": {
"temperature": 0.4,
"maxOutputTokens": 256
}
}'响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
candidates[] | array | 模型生成的候选响应。 |
candidates[].content.role | string | 响应内容角色,通常为 model。 |
candidates[].content.parts[] | array | 响应内容块。文本位于 parts[].text;工具调用位于 parts[].functionCall。 |
candidates[].finishReason | string | 候选响应的结束原因。 |
usageMetadata | object | Token 用量,包含 promptTokenCount、candidatesTokenCount 和 totalTokenCount 等字段。 |
{
"candidates": [
{
"content": {
"role": "model",
"parts": [{"text": "API 用于定义软件系统之间交换请求和响应的方式。"}]
},
"finishReason": "STOP",
"index": 0
}
],
"usageMetadata": {
"promptTokenCount": 12,
"candidatesTokenCount": 14,
"totalTokenCount": 26
}
}官方参考:GenerateContent API
Last updated on