模型与对话

Gemini：文本与媒体理解接口

使用 contents 和 parts；区分普通返回、SSE流和inlineData媒体输入。

约 6 分钟阅读·面向开发者

Gemini原生协议把消息放在 contents 中，每条消息包含 parts。文字和媒体可组合在同一条消息里；“理解图片或视频”与“生成图片或视频”是不同能力，不能混为一谈。

方法、地址与鉴权#

用途	归壹完整地址
普通生成	POST https://univto.com/v1beta/models/{模型ID}:generateContent
SSE流式生成	POST https://univto.com/v1beta/models/{模型ID}:streamGenerateContent?alt=sse
Gemini格式模型目录	GET https://univto.com/v1beta/models

用当前模型的精确ID替换路径中的{模型ID}，不保留大括号，不再重复添加models/。请求头使用 x-goog-api-key 携带归壹API密钥，并对JSON设置 Content-Type: application/json；请勿把密钥拼进网址。

关键参数#

字段	含义与用法
contents[].role	user表示用户输入，model表示模型历史回答；不是assistant
contents[].parts[].text	一段文字输入
contents[].parts[].inlineData	媒体的MIME类型与纯Base64数据
systemInstruction	系统说明，常以parts中的text提供
generationConfig.maxOutputTokens	输出长度设置；实际可设范围及思考语义取决于模型
generationConfig.temperature / topP / topK	模型支持时调整采样
tools / safetySettings	按当前模型支持的工具与安全参数使用，不要把其他接口字段直接复制进来

先发一条最简单的文字#

在自己的终端设置，示例只有占位值

export GUIYI_API_KEY='替换成你自己的归壹API密钥'
export GUIYI_MODEL='替换成该接口可用的完整模型ID'

路径模型来自本机环境变量，运行会正常计费

curl --fail-with-body "https://univto.com/v1beta/models/${GUIYI_MODEL}:generateContent" \
  -H "x-goog-api-key: ${GUIYI_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "你好，请用一句话介绍自己。"}]
    }]
  }'

识别媒体：inlineData怎么填写#

模型和线路已开放相应媒体能力时，可把text与inlineData放在同一parts数组。inlineData.data只放文件的Base64编码，不含data:image/...;base64,前缀；mimeType必须与真实文件一致。文件大小、时长与支持类型按该模型规定，Base64会增加请求体积。

媒体输入结构示意；替换Base64占位后才是有效媒体请求

{
  "contents": [{
    "role": "user",
    "parts": [
      {"text": "请描述这张图片。"},
      {"inlineData": {"mimeType": "image/jpeg", "data": "YOUR_IMAGE_BASE64"}}
    ]
  }]
}

媒体示例	常见mimeType	需要确认
图片	image/jpeg、image/png	所选模型支持识图，不是仅文本
PDF	application/pdf	模型与当前线路支持文档内容解析
音频	audio/mpeg、audio/wav	支持对应格式、时长与输入方式
视频	video/mp4	支持视频理解及对应文件限制，不代表生成视频

返回与流式解析#

普通返回在 candidates[].content.parts[] 中提供内容。逐项处理text，不假定第一个候选永远存在，也不把空数组当作成功回答；检查finishReason、safetyRatings以及返回提供的拦截或错误说明。usageMetadata通常提供promptTokenCount、candidatesTokenCount与totalTokenCount，更多细项以实际返回为准。

开启流式时使用streamGenerateContent并保留alt=sse，按SSE事件读取每段候选内容，合并文本后仍检查最终结束原因与错误事件。不要把它套用为Chat的choices[].delta，也不要在断线后自动重新提交大文件。