Skip to Content
文本生成Gemini API

Gemini API

Gemini GenerateContent
接口POST /v1beta/models/{model}:generateContent

鉴权方式:Authorization: Bearer <YOUR_API_KEY>。

外部 URL 可以是公开 HTTPS URL 或签名 URL。每个请求或载荷最多处理 100 MB 的外部文件,处理期间需保持 URL 可访问。

详见 Gemini 文件输入说明。

请求参数

参数类型必填说明
model(路径)string是/v1beta/models/{model}:generateContent 中的模型 ID。
contentsarray是对话内容列表。每项包含 parts,文本内容使用 {“text”:”…”}。多轮对话需包含此前的用户与模型消息。
systemInstructionobject否系统指令,使用包含文本内容的 parts 数组。
generationConfig.temperaturenumber否控制输出随机性,取值范围为 0.0 至 2.0;默认值因模型而异。Gemini 3.6 Flash 及更新模型会忽略此字段。
generationConfig.topPnumber否核采样阈值。
generationConfig.topKnumber否将候选范围限制为概率最高的 Token。
generationConfig.maxOutputTokensinteger否输出最大 Token 数,具体上限因模型而异。
generationConfig.candidateCountinteger否返回的候选响应数量,默认为 1。
generationConfig.stopSequencesstring[]否遇到指定字符串时停止生成。
generationConfig.responseMimeTypestring否响应 MIME 类型;结构化 JSON 输出可使用 application/json。
generationConfig.responseSchemaobject否结构化 JSON 输出的 Schema,需与 responseMimeType: “application/json” 配合使用。Gemini API 已将此字段标记为弃用。
generationConfig.thinkingConfigobject否思考选项,例如 thinkingLevel、thinkingBudget 或 includeThoughts,支持情况因模型而异。
toolsarray否工具定义,可包含函数声明或模型支持的内置工具。
toolConfig.functionCallingConfigobject否函数调用模式(AUTO、ANY 或 NONE),也可限定允许调用的函数名称。
safetySettingsarray否设置请求的安全类别和拦截阈值。
cachedContentstring否作为上下文使用的缓存内容名称。

调用示例

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.rolestring响应内容角色,通常为 model。
candidates[].content.parts[]array响应内容块。文本位于 parts[].text;工具调用位于 parts[].functionCall。
candidates[].finishReasonstring候选响应的结束原因。
usageMetadataobjectToken 用量,包含 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