Gemini API/Gemini 请求参数与多模态内容格式

Gemini generateContent 顶层请求参数、contents 对话历史、多模态 inlineData、文件引用与系统指令自动提取提升完整参考。

Gemini 请求参数与多模态内容格式

本文档详细说明通过 UniGateway 调用 Gemini API(POST /v1beta/models/{model}:generateContent 与 streamGenerateContent)时的顶层请求参数、contents 对话历史数组、多模态内容块格式(inlineData 与 fileData)、系统指令(systemInstruction)自动提取提升以及安全设置(safetySettings)。


章节导引

本篇为 Gemini API 参考文档的第 3 章节:

  1. Gemini 概览与接入
  2. generateContent 概述与快速开始
  3. 请求参数与多模态内容格式(当前章节)
  4. 扩展思考与思维链签名
  5. 工具调用与搜索检索
  6. 结构化输出与生成配置
  7. 响应、流式与错误处理

顶层请求参数概览

Gemini generateContent 端点接收 JSON 格式的请求载荷。主要顶层参数如下:

参数类型必填说明
contentsarray<object>是按时间顺序排列的完整对话历史消息列表。
systemInstructionobject否系统角色业务规则指令,格式为 {"parts": [{"text": "..."}]}。
generationConfigobject否文本生成超参数、思考配置、采样与结构化输出配置。
toolsarray<object>否工具定义数组(函数声明 functionDeclarations、Google Search、代码执行等)。
toolConfigobject否工具调用策略配置(如 functionCallingConfig)。
safetySettingsarray<object>否内容安全与有害内容拦截阈值过滤设置。
cachedContentstring否关联的上下文缓存资源名称(格式形如 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_HARASSMENTBLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH
HARM_CATEGORY_HATE_SPEECHBLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH
HARM_CATEGORY_SEXUALLY_EXPLICITBLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH
HARM_CATEGORY_DANGEROUS_CONTENTBLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH

网关处理规则:

  • 自动剔除 category 为空或等于 HARM_CATEGORY_UNSPECIFIED 的项;
  • 若客户端传入了空数组 safetySettings: [],网关在出站前主动删除该顶层键,避免上游校验警告。

下一步