Gemini 3 / 3.1 图像生成（Google 原生协议）

ModelGo 按 Google Gemini API 的 generateContent 协议原样接收图像生成请求：contents + generationConfig，同步返回 candidates[].content.parts[].inlineData。网关负责路由到供应商并计费；由哪家供应商渲染对调用方不可见。URL 路径中的模型名是唯一权威，请求体中无需再写模型。

使用 Google GenAI SDK 时，把 http_options.base_url 指向 https://api.modelgo.com、api_key 换成 ModelGo API Key 即可。鉴权头同时接受 x-goog-api-key: $KEY 与 Authorization: Bearer $KEY。

>

Google 新推出的 Interactions API 暂不支持，请使用 generateContent。

1. 创建图像

POST https://api.modelgo.com/v1beta/models/{model}:generateContent（也接受 /v1/models/...）

文生图

curl "https://api.modelgo.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感"}]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "2K"}
    }
  }'

图生图

参考图以 inlineData（base64）或 fileData（公网 URL）放进 parts：

curl "https://api.modelgo.com/v1beta/models/gemini-3-pro-image:generateContent" \
  -H "x-goog-api-key: $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [
      {"text": "把背景换成霓虹夜景，保留猫的姿态"},
      {"inlineData": {"mimeType": "image/png", "data": "<base64>"}}
    ]}],
    "generationConfig": {"responseModalities": ["IMAGE"], "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"}}
  }'

fileData 写法：{"fileData": {"fileUri": "https://example-cdn.com/cat.png"}}，必须是上游可直接 GET 的直链。

响应

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"inlineData": {"mimeType": "image/png", "data": "iVBORw0KGgo..."}}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 18,
    "candidatesTokenCount": 1680,
    "totalTokenCount": 1698,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 18}],
    "candidatesTokensDetails": [{"modality": "IMAGE", "tokenCount": 1680}]
  },
  "modelVersion": "gemini-3.1-flash-image"
}

• 图像在 parts[].inlineData.data（base64）。responseModalities 含 TEXT 时，parts 中可能另有 {"text": ...} 段。
• modelVersion 回显请求路径中的模型名。

保存到文件：

curl -s "https://api.modelgo.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "x-goog-api-key: $MODELGO_API_KEY" -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"a red ball on a wooden table"}]}],"generationConfig":{"responseModalities":["IMAGE"]}}' \
  | python3 -c '
import sys, json, base64
for p in json.load(sys.stdin)["candidates"][0]["content"]["parts"]:
    if "inlineData" in p:
        open("out.png", "wb").write(base64.b64decode(p["inlineData"]["data"])); break'

2. 参数说明

• candidateCount > 1 → 400：一次只出一张。
• tools、responseSchema / responseMimeType → 400：图像模型不支持工具调用与结构化输出。
• :streamGenerateContent → 400：图像生成不支持流式。
• 模型不提供的 imageSize（如 gemini-3.1-flash-lite-image 传 2K）→ 400，不会静默降档生成，不产生费用。
• 按可交付档位选路。 网关只把请求交给能按所声明档位交付的供应商；若当前无供应商能出该档位，返回 400，不产生费用。

分辨率档位

档位决定总像素量级，精确宽高由 aspectRatio 决定；不指定 aspectRatio 时缺省为供应商的近似 16:9 输出。

3. 完整示例（Python，Google GenAI SDK）

import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["MODELGO_API_KEY"],
                      http_options={"base_url": "https://api.modelgo.com"})

resp = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents="一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感",
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
    ),
)
for part in resp.candidates[0].content.parts:
    if part.inline_data:
        open("cat.png", "wb").write(part.inline_data.data)
print(resp.usage_metadata.candidates_token_count)

图生图时把 contents 换成列表：["把背景换成霓虹夜景", types.Part.from_bytes(data=open("cat.png","rb").read(), mime_type="image/png")]。

4. 计费口径

• 按 token 计费：promptTokensDetails 中的文本按 input、图像按 image_input；candidatesTokensDetails 中 IMAGE 按 image_output、TEXT 按 output。
• 输出图像 token 随档位增长（实测）：1K ≈ 1120，2K ≈ 1680，4K ≈ 2000。
• 请求时预授权冻结，响应返回后按 usageMetadata 实际值结算。
• 请求被拒（400）或生成失败不计费，预授权自动释放。
• 各模型单价以控制台「模型列表」中的价格为准。

常见错误