Gemini の画像生成

Gemini の画像生成(通称 Banana)は OpenAI Images API を使い、Base64 画像を同期で返します。2 つのグループは編集エンドポイントと課金方式が異なります。

利用できるモデル

選び方:4K が必要なら gemini-3-pro-image のみです。gemini-3.1-flash-image は 1K と 2K が同価格です。複数の参照画像を合成する用途に Lite は向きません(複数参照画像向けに最適化されていません)。

2 つのグループの違い:

「Gemini 公式ダイレクト」では画像モデルを /v1/chat/completions からも呼び出せ、画像は markdown に埋め込まれた data URL で返ります。

リクエストパラメータ

生成

POST /v1/images/generations、JSON ボディ。OpenAI Images の構造で送り、Gemini ネイティブの generateContent ペイロードは送らないでください。

aspect_ratio に指定できる値:1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9。

image_config には等価な 3 つの書き方があります。複数ある場合は次の順で最初のものが使われます。

• google.image_config
• extra_body.google.image_config(OpenAI SDK での書き方)
• トップレベルのフラットな aspect_ratio / image_size

モデルの段階を超える image_size を明示すると 400 が返ります。

size の WIDTHxHEIGHT は比率を理由に拒否されません。最も近い公式比率に割り当てられ、段階(長辺から算出)はエラーなしでモデルの最高段階まで黙って下げられます。

たとえば gemini-3.1-flash-image に 4096x4096 を送ると 2K 画像が返ります。モデルの段階を超える段階略称は 400 になります。

n は出力段階ごとにも上限があります:4K ≤ 2、2K ≤ 5、1K ≤ 10(レスポンスサイズの上限)。超えると 400 が返ります。

参照画像

どちらのグループも generations の image / images で参照画像を渡します(JSON のみ)。各要素は http(s) URL または Data URL の文字列で、URL はサーバーから取得でき、内部アドレスを指していない必要があります。

「Gemini 全モデル（画像生成含む）」は 4 MiB を超える参照画像を自動で圧縮してから生成します。gemini-2.5-flash-image の参照画像は公式に最大 3 枚です。Data URL の例は data:image/png;base64,iVBORw0KGgo… で、MIME は画像と一致させてください。

編集(「Gemini 全モデル（画像生成含む）」のみ)

POST /v1/images/edits は multipart/form-data を推奨し、JSON(参照画像は URL / Data URL)も受け付けます。参照画像が 1 枚以上必要です。

「Gemini 公式ダイレクト」にはこのエンドポイントがなく、404 が返ります。編集は generations に参照画像を付けて行ってください。どちらのグループも mask には対応せず、送ると 400 が返ります。

非同期

HTTP ヘッダー Prefer: respond-async を付けると、すぐに 202 Accepted と task_id が返ります。2K / 4K の大きな画像では、長いリクエストが CDN のタイムアウトで切れないよう、こちらを推奨します。

レスポンス

同期リクエストは OpenAI Images の JSON を返し、画像は data[].b64_json に入ります。

{
  "created": 1760000000,
  "model": "gemini-3-pro-image",
  "data": [
    {
      "b64_json": "/9j/4AAQSkZJRgABAQ...",
      "mime_type": "image/jpeg"
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1120,
    "total_tokens": 1162
  }
}

非同期タスク

送信するとすぐに次が返ります。

{
  "task_id": "imgtask_EXAMPLE",
  "status": "pending",
  "status_url": "/v1/images/tasks?task_id=imgtask_EXAMPLE"
}

完了後のレスポンス:

{
  "task_id": "imgtask_EXAMPLE",
  "status": "completed",
  "result_content": "![image](/assets-runtime/2026/09/xxxxxxxxxxxx.png)",
  "usage": {
    "cost": 1.36,
    "currency": "CNY",
    "cost_cny": 1.36,
    "cost_usd": 0.2
  }
}

例

テキストから画像

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "日の当たる木のテーブルに置いた陶器のティーポット、商品写真",
    "google": {
      "image_config": { "aspect_ratio": "16:9", "image_size": "2K" }
    }
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > result.png

curl の例には jq が必要です。data[].mime_type が image/jpeg の場合は拡張子を .jpg に変えてください。

参照画像による編集

curl https://api.hop-base.com/v1/images/generations \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "1 枚目のカップを 2 枚目の配色に変え、ほかはそのまま",
    "images": [
      "https://example.com/cup.png",
      "https://example.com/palette.png"
    ],
    "size": "1024x1024"
  }'

注意事項

• /v1/images/edits があるのは「Gemini 全モデル（画像生成含む）」だけで、もう一方のグループでは generations で参照画像を渡します。
• 結果は Base64 で JPEG の場合もあるため、保存前に data[].mime_type を確認してください。
• mask には対応していないため、変更したい範囲は prompt で説明してください。
• 透明背景は出力できず、background: "transparent" は 400 になります。
• stream: true には対応していないため、デフォルトの同期モードか非同期タスクを使ってください。
• 2K / 4K の画像では Prefer: respond-async を付けるか、同期リクエストのクライアント読み取りタイムアウトを長めに設定してください。
• 有料リクエストの前に、使うキーで GET /v1/models から完全な ID を取得し、段階のサフィックスを自分で付けないでください。

よくあるエラー

パラメータが不正な場合は生成前に 400 が返り、課金されません。

# 「Gemini 全モデル（画像生成含む）」
prompt must not be empty
n must be between 1 and 10 for model gemini-3-pro-image
n=3 is too large for 4K output on model gemini-3-pro-image; at most 2 images per request at this size (response size limit); lower n or send separate requests
model gemini-3.1-flash-image does not support tier 4K; supported: 1K, 2K
model gemini-3-pro-image: size "big" is not valid; expected WIDTHxHEIGHT (any aspect ratio, mapped to the nearest official tier) or 1K/2K/4K
aspect_ratio "7:3" is not supported for model gemini-3-pro-image; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_size "4K" is not supported for model gemini-3.1-flash-image; supported: 1K, 2K
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
mask is not supported for Gemini image models; remove mask and describe the region to edit in the prompt
too many reference images: at most 14 are supported for this model, got 15

# 「Gemini 公式ダイレクト」
missing prompt
Gemini image generation does not support stream=true; send a non-streaming request
n must be at most 10
n=6 is too large for 2K output on model gemini-3.1-flash-image; at most 5 images per request at this size (response size limit); lower n or send separate requests
Images generations only accepts a JSON request body: ...
size 4K is not supported for model gemini-3.1-flash-image; supported tiers: 1K, 2K
size "banana" is not valid for model gemini-3-pro-image; use auto, WIDTHxHEIGHT (e.g. 1024x1024, mapped to the nearest supported aspect ratio and capped at the model's largest tier), or one of: 1K, 2K, 4K
image_config.aspect_ratio "7:3" is not supported; allowed values: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
image_config.image_size "4K" is not supported for model gemini-3.1-flash-image; allowed values: 1K, 2K
mask is not supported for model gemini-3-pro-image; remove mask and describe the region to edit in the prompt
background=transparent is not supported for model gemini-3-pro-image; Gemini image models cannot output transparent images
reference image 1: reference image exceeds the 20MB limit
reference image 1: reference image URL must not point to an internal address
reference image 1: reference image download returned HTTP 404
reference image 1: reference file is not a supported image type

課金

「Gemini 全モデル（画像生成含む）」は実際に納品した枚数で課金し、「Gemini 公式ダイレクト」はトークン単位で、実際に生成された段階に応じて課金します。不正なパラメータと部分的な失敗は課金されません。非同期タスクの終了後は、照会レスポンスの usage.cost が実際の課金額です。

単価は各モデルカードと、ログイン後のモデル一覧で確認できます。

次のステップ

• 画像生成の概要
• GPT Image、Seedream、Grok Imagine の画像生成、Kling の画像生成
• API リファレンス:画像の生成、画像の編集、画像タスクの照会
• エラーが出たらトラブルシューティングを参照