Gemini 原生

请求体是 Gemini 的原生结构，和 OpenAI 的平铺 JSON 完全不同：

• contents (array / 必填) — 对话内容，每条含 role 与 parts。
• contents[].parts (array / 必填) — 文本用 {"text": "..."}，图片用 {"inlineData": {...}}。
• generationConfig.responseModalities (array / 必填) — 必须同时包含 TEXT 与 IMAGE，否则不返回图片。
• generationConfig.imageConfig (object / 可选) — 画幅与分辨率，见请求参数。

The body is Gemini's native shape, nothing like OpenAI's flat JSON:

• contents (array / required) — the conversation, each turn with role and parts.
• contents[].parts (array / required) — text as {"text": "..."}, images as {"inlineData": {...}}.
• generationConfig.responseModalities (array / required) — must include both TEXT and IMAGE or no image is returned.
• generationConfig.imageConfig (object / optional) — aspect and size, described under request parameters.

inlineData 只接受 Base64，不接受 URL。data 是纯 Base64，不带 data:image/png;base64, 前缀，mimeType 写实际格式。

inlineData takes Base64 only, never a URL. data is raw Base64 with no data:image/png;base64, prefix, and mimeType names the real format.

图片在 candidates[0].content.parts 里，以 inlineData 返回：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "这是你要的图片" },
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUg..." } }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1314
  }
}

• candidates[].content.parts[] (array) — 文本段带 text，图片段带 inlineData。
• candidates[].content.parts[].inlineData.data (string) — 纯 Base64，自行拼 data:<mimeType>;base64, 才能放进 <img>。
• candidates[].finishReason (string) — 结束原因，被安全策略拦截时为 SAFETY。
• usageMetadata (object) — token 用量，含 promptTokenCount、candidatesTokenCount、totalTokenCount。

Images come back in candidates[0].content.parts as inlineData:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "这是你要的图片" },
          { "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgoAAAANSUhEUg..." } }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 1290,
    "totalTokenCount": 1314
  }
}

• candidates[].content.parts[] (array) — text parts carry text, image parts carry inlineData.
• candidates[].content.parts[].inlineData.data (string) — raw Base64; prepend data:<mimeType>;base64, to use it in an <img>.
• candidates[].finishReason (string) — why it stopped; SAFETY when blocked.
• usageMetadata (object) — token usage: promptTokenCount, candidatesTokenCount, totalTokenCount.

已有 Gemini SDK 的项目用原生，其余用 OpenAI 兼容。

Projects already on a Gemini SDK should use the native path; everything else uses the OpenAI-compatible one.

常见 400 原因：generationConfig 位置写错；inlineData.data 带了 data: 前缀；参考图超过 14 张。

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

Common 400 causes: generationConfig in the wrong place; a data: prefix inside inlineData.data; more than 14 reference images.

For more status codes see Error codes and rate limits; for troubleshooting see the FAQ.

parts 里只放文本是文生图；先放 inlineData 再放文本是编辑，顺序会影响结果。imageConfig 控制画幅与分辨率档位。

Text-only parts is text to image; an inlineData part followed by text is an edit, and order affects the result. imageConfig sets aspect ratio and resolution tier.