Gemini 请求参数与多模态内容格式
本文档详细说明通过 UniGateway 调用 Gemini API(POST /v1beta/models/{model}:generateContent 与 streamGenerateContent)时的顶层请求参数、contents 对话历史数组、多模态内容块格式(inlineData 与 fileData)、系统指令(systemInstruction)自动提取提升以及安全设置(safetySettings)。
章节导引
本篇为 Gemini API 参考文档的第 3 章节:
- Gemini 概览与接入
- generateContent 概述与快速开始
- 请求参数与多模态内容格式(当前章节)
- 扩展思考与思维链签名
- 工具调用与搜索检索
- 结构化输出与生成配置
- 响应、流式与错误处理
顶层请求参数概览
Gemini generateContent 端点接收 JSON 格式的请求载荷。主要顶层参数如下:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
contents | array<object> | 是 | 按时间顺序排列的完整对话历史消息列表。 |
systemInstruction | object | 否 | 系统角色业务规则指令,格式为 {"parts": [{"text": "..."}]}。 |
generationConfig | object | 否 | 文本生成超参数、思考配置、采样与结构化输出配置。 |
tools | array<object> | 否 | 工具定义数组(函数声明 functionDeclarations、Google Search、代码执行等)。 |
toolConfig | object | 否 | 工具调用策略配置(如 functionCallingConfig)。 |
safetySettings | array<object> | 否 | 内容安全与有害内容拦截阈值过滤设置。 |
cachedContent | string | 否 | 关联的上下文缓存资源名称(格式形如 cachedContents/xxx)。 |
contents 消息结构与 Protobuf Oneof 规范
Gemini API 采用消息列表形式组织交互历史,每条消息包含角色(role)与内容块(parts)。
1. contents 核心规范三维对照
| 参数 / 场景 | Google Gemini 官方规范 | UniGateway 处理规则 |
|---|---|---|
| Protobuf Oneof 数据字段互斥约束 | Gemini Protobuf 定义规定,单个 parts 元素内部的载体字段(text、inlineData、fileData、functionCall、functionResponse、executableCode、codeExecutionResult)为互斥的 Oneof 关系。如果单个对象内同时包含多个载体,上游将直接抛出反序列化校验错误。 | 复合内容块智能拆分:网关在出站前深度扫描每个 part。若检测到同时包含空文本(text: "")与 inlineData,自动移除空 text 字段;若包含多个实际数据载体,网关自动将其按规范展开为多个独立的单载体 part,并保证 thought 与 thoughtSignature 附着在正确的工具或文本分支上。 |
| 空消息与空内容块过滤 | 上游拒绝包含空 parts 数组的消息或空 {} 内容块,否则返回 400 contents[N].parts must not be empty。 | 空内容防护过滤:网关自动剔除 parts 为空数组的消息以及无效的空 part 对象;若整段请求过滤后有效内容为空,网关返回对齐官方规范的标准 400 错误。 |
| 角色取值约束 | 官方规范仅允许 role: "user" 或 role: "model"。在多轮交互中,角色应严格交替。 | 角色对齐与多轮修正:网关自动将客户端传入的 assistant 角色标准化映射为 model;若连续出现相同角色消息,网关安全保留或合并,确保符合上游通道要求。 |
系统指令自动提取提升
Gemini 官方规范要求系统角色指令必须放置在顶层 systemInstruction 对象中,contents 数组中仅允许 user 与 model 角色。许多传统客户端或 IDE 会在 contents 头部直接发送 role: "system" 消息。
| 参数 / 场景 | Google Gemini 官方规范 | UniGateway 处理规则 |
|---|---|---|
contents 中夹带 role: "system" | 传入 role: "system" 会导致上游返回 400 Invalid role: system。 | 前置指令自动提升:网关自动扫描 contents:<br>1. 将开头的连续 role: "system" 消息提取,合并写入顶层 systemInstruction.parts;<br>2. 会话中段出现的非首位 system 消息自动将其角色转换为 user 以保留提示词语义;<br>3. 若全部消息均为 system 角色,保留最后一条作为 user 角色,确保 contents 始终具备非空对话轮次。 |
| Snake 命名与空结构清理 | 客户端传入 system_instruction 或包含空 parts: [] 的系统指令对象。 | 结构合并与修剪:将 system_instruction 自动合并迁移至标准 systemInstruction;若系统指令中的 parts 数组为空,网关自动移除 systemInstruction 节点,避免触发上游非空校验报错。 |
多模态输入:图像与文件格式
Gemini 原生支持通过 inlineData(Base64 编码)或 fileData(文件 URI 引用)传递多模态资源。
1. 图像载体 inlineData
适用于小至中型图像(JPEG、PNG、WEBP、HEIC 等格式),将文件内容转为 Base64 字符串后嵌入请求体:
{
"role": "user",
"parts": [
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "/9j/4AAQSkZJRgABAQEASABIAAD..."
}
},
{
"text": "描述这张图片中的关键信息。"
}
]
}
网关在入站与跨协议转换时:
- 同时兼容
inlineData与inline_data两种命名; - 配合图像生成与理解模型,在必要时自动将 OpenAI 格式的
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}双向转译。
2. 文件引用 fileData
适用于大尺寸音视频或通过 Google File API 事先上传的文件:
{
"role": "user",
"parts": [
{
"fileData": {
"fileUri": "https://generativelanguage.googleapis.com/v1beta/files/abc123xyz",
"mimeType": "application/pdf"
}
},
{
"text": "总结该 PDF 的主要章节结论。"
}
]
}
安全设置 safetySettings
Gemini 允许对仇恨言论、危险内容、性露骨内容及骚扰内容等维度设置安全过滤阈值。
类别 (category) | 可选阈值 (threshold) |
|---|---|
HARM_CATEGORY_HARASSMENT | BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH |
HARM_CATEGORY_HATE_SPEECH | BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH |
HARM_CATEGORY_SEXUALLY_EXPLICIT | BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH |
HARM_CATEGORY_DANGEROUS_CONTENT | BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH |
网关处理规则:
- 自动剔除
category为空或等于HARM_CATEGORY_UNSPECIFIED的项; - 若客户端传入了空数组
safetySettings: [],网关在出站前主动删除该顶层键,避免上游校验警告。
下一步
- 了解扩展思考与思维链签名保持机制:扩展思考与思维链签名
- 配置自定义函数与 Google Search:工具调用与搜索检索
- 探索结构化输出与采样参数:结构化输出与生成配置