API 接入

Gemini Generate Content

contents、媒体、工具与图片输出

端点与鉴权

POST https://www.yunqiai.chat/v1beta/models/{model}:generateContent

请求头使用 x-goog-api-key: <API_KEY> 和 Content-Type: application/json。路径中的 model 使用完整模型 ID，拼接 URL 时按路径参数编码。

流式请求使用 POST /v1beta/models/{model}:streamGenerateContent?alt=sse。普通 generateContent 不通过 stream:true 切换为流式。

json

{
  "contents": [{"role":"user","parts":[{"text":"仅回复 READY"}]}],
  "generationConfig": {"maxOutputTokens":4096}
}

配置字段

字段	用途
contents	历史消息，role 为 user 或 model，内容为 parts 数组
systemInstruction.parts	系统指令，与 contents 分开
generationConfig.maxOutputTokens	输出预算，需同时为推理及最终结果留出空间
generationConfig.thinkingConfig	thinkingLevel / thinkingBudget 等型号专属设置，不混用不支持的字段

gemini-3.7-flash 和 gemini-3.8-flash 的 thinkingLevel 不包含 minimal，可用值与 gemini-3.5-flash 有区别。

内联媒体

图片、音频、视频、PDF 均使用独立 part：

json

{
  "contents": [{"role":"user","parts":[
    {"text":"描述视频中先后出现的画面，并给出时间顺序"},
    {"inlineData":{"mimeType":"video/mp4","data":"<BASE64>"}}
  ]}]
}

Base64 不带 data URI 前缀，MIME 需与文件编码一致。文件大小、上下文预算、视频帧采样和输出限制都会影响读取范围，见媒体输入。本页使用内联文件，不依赖 /upload/v1beta/files；本地路径或未上传文件的 fileUri 均不能代替文件内容。

工具与多轮

多轮对话按顺序传入 user / model contents。响应 part 含 thoughtSignature 时，连同其他字段原样保存，并在下一轮回传完整内容，而非只保留 text。

当前接入暂不支持原生工具结果回传和强制 JSON Schema。tools / functionResponse、responseMimeType、responseJsonSchema 不在本版支持范围内。通过提示词要求返回 JSON 时，应用仍需严格解析和校验，代码围栏也应按格式异常处理。

图像生成与参考图

图片模型在 generationConfig 设置 responseModalities:["TEXT","IMAGE"]，尺寸相关设置位于 imageConfig，不是 OpenAI Images 的顶层 size。

json

{
  "contents": [{"role":"user","parts":[
    {"text":"保留第一张产品外形与第二张包装配色，生成正面产品图"},
    {"inlineData":{"mimeType":"image/png","data":"<FIRST_BASE64>"}},
    {"inlineData":{"mimeType":"image/jpeg","data":"<SECOND_BASE64>"}}
  ]}],
  "generationConfig": {
    "responseModalities":["TEXT","IMAGE"],
    "imageConfig":{"aspectRatio":"1:1","imageSize":"1K"}
  }
}

每张参考图分别放入 inlineData，提示词说明各图的用途。多轮编辑时保留上一轮完整 model parts 和签名，再追加新的 user 指令；图片的 Base64 无需写入提示词。

imageConfig.imageSize 可填 1K、2K 或 4K，aspectRatio 可填 1:1、16:9、9:16 等比例。实际宽高由两者共同决定，长边未必固定为 1024。输出可能同时包含中间预览和最终图片。

遍历 candidates[].content.parts[]，分别读取 text 与 inlineData / inline_data。带 thought:true 的文字或图片属于中间推理内容，其中的预览图可能低于请求分辨率。保存图片时跳过这些 part，读取剩余图片、解码并按文件格式保存。响应若只有文字或中间预览，则没有返回最终图片。

安装 requests pillow 后可运行 gemini-images.py。多张参考图重复传入 --image，使用 --size 2K --aspect 16:9 设置规格。--history private-history.json 保存完整消息与签名，后续编辑继续使用同一文件。历史文件含原始图片和对话内容，请限制访问权限并排除在版本控制之外。

bash

python gemini-images.py --prompt '保留两张参考图的独有形状、颜色和标识，将图1放左上、图2放右下' \
  --image first.png --image second.png --size 2K --aspect 1:1 \
  --history private-history.json --out image-round-1
python gemini-images.py --prompt '保持两个主体不变，仅将背景改成白色' \
  --size 2K --aspect 1:1 --history private-history.json --out image-round-2

结束状态

响应需检查 promptFeedback、candidates[].finishReason、safetyRatings 和 usageMetadata。MAX_TOKENS 表示截断，SAFETY 等表示受限结束，即使 HTTP 为 200 也需单独处理。流式请求以候选的最终结束状态为准，SSE 未必返回 OpenAI 风格的 [DONE] 标记。