Gemini画像生成REST API: 今すぐ使えるcURLガイド

2026年3月27日時点で、Gemini画像生成をraw RESTで始める最も安全なdefaultは POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent です。 まずここから始めて、responseModalities と imageConfig を入れ、返ってきた inlineData を画像として保存してから、OpenAI互換レイヤーや別モデルを考えるのが最も安全です。

この順番が重要なのは、Googleの答えが今でも複数ページに分散しているからです。画像生成ガイド はnative Geminiの流れを説明し、API reference は generateContent と imageConfig の契約を定義し、OpenAI compatibility docs は別の互換ルートを示します。これらをまとめて読むと、どれも同じ「最初の答え」に見えがちですが、新しいraw REST実装ではそうではありません。

もう一つ上で固定しておきたい前提があります。現在のGemini 3系画像モデルはまだpreview扱いで、しかも画像モデルの推奨パスはここ数か月でかなり動いています。公式のOpenAI互換画像例では今も gemini-2.5-flash-image が出てきますが、native Geminiの最新ドキュメントでは gemini-3.1-flash-image-preview と gemini-3-pro-image-preview が中心です。この違いを整理しないまま調べ始めると、URLの問題とモデルの問題を混同しやすくなります。

要点まとめ

hostとpathの切り分けだけ知りたいなら Gemini画像生成APIのBase URL が先です。SDK例も含めて見たいなら Gemini画像生成コード例 が次に合います。

まずはnative Gemini RESTルートを使う

新しいREST実装では、まずこの考え方を固定すると楽になります。Geminiの画像生成は、独立した謎のimage hostではなく、画像を返すnative Gemini API requestです。 現在のAPI referenceは依然として generateContent の中で画像生成を定義しており、画像生成ガイドもその同じmethod familyに乗っています。

raw RESTで最初に確認したいのは普通この3つです。

• 今の正しいhostとmodel pathは何か
• 画像に効く設定はどこに置くのか
• SDKを介さない実際のresponse shapeはどう見えるか

native routeはこの3点を一番素直に見せてくれます。hostが明確で、docsも最新で、imageConfig もそのままrequestに置けます。cURLで確認したい人や、自前wrapperを作る人にはここが最も判断しやすいdefaultです。

実務上のstarting modelは gemini-3.1-flash-image-preview です。Googleの modelsページ はこれを現行の高効率画像ラインとして見せていて、gemini-3-pro-image-preview はpremium branchとして残しています。旧ラインの gemini-2.5-flash-image もまだ存在しますが、Googleの deprecationsページ では 2026年10月2日 がshutdown dateとして出ており、代替として gemini-3.1-flash-image-preview が示されています。

動くcURL requestをまず1本コピーする

最初から複雑なworkflowにしないでください。まず証明したいのはhost、model、image outputです。最初のrequestは退屈でいいので、1つのprompt、1つのcurrent model、1つの画像出力に絞ります。

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a clean 16:9 product image of a matte black travel mug on a light concrete surface with soft studio lighting and premium ecommerce styling."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

このrequestは、native path、current model、そしてimage controlsを同時に検証できます。現在の API reference では、imageConfig の imageSize は 512、1K、2K、4K を取れます。だからこそ、画像設定をちゃんと使いたいなら互換レイヤーよりnative routeの方が分かりやすいわけです。

もしtext-heavy graphicsやより高価なvisual outputが必要なら、model pathだけ gemini-3-pro-image-preview に差し替えます。次の関心がREST shapeではなく料金なら、Gemini image generation API pricing の方が役に立ちます。

REST responseから画像を保存する

多くのREST記事が省略するのがこの段階です。native Gemini responseは完成済みのファイルパスを返すのではなく、画像のbytesを inlineData としてJSONの中に返します。

そのため、初回のraw RESTでは「JSONしか返ってこないから失敗した」と勘違いしがちです。多くの場合、失敗ではなく、最後のdecodeと保存がまだ終わっていないだけです。

native routeでの基本手順は次の通りです。

1. candidates[0].content.parts を読む
2. inlineData を持つpartを探す
3. .inlineData.data を取り出す
4. base64 decodeしてファイルに書く

shellならこう書けます。

bash
curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [
        {
          "text": "Create a square studio photo of a red ceramic teacup on a white background."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }' \
| jq -r '.candidates[0].content.parts[] | select(.inlineData) | .inlineData.data' \
| base64 --decode > gemini-image.png

macOSでは base64 -D を使う場合があります。重要なのはshellオプションではなく、successful native responseはJSONの中に画像を持っており、最後に自分でdecode-to-fileする必要がある という点です。

OpenAI互換画像パスが本当に正しい場面

OpenAI互換ルートは存在しますし、使い道もあります。Googleの現行 compatibility docs には次のURLが残っています。

text
https://generativelanguage.googleapis.com/v1beta/openai/

画像endpointは:

text
/v1beta/openai/images/generations

既存のOpenAI-style clientを大きく変えたくない、という事情が明確ならこのルートは合理的です。migration costを下げたい、という目的には合っています。

ただし、これは “gemini image generation rest api” の最良defaultではありません。この検索で知りたいのは通常 現在のnative Gemini REST contract であって、OpenAIライクなclient surfaceを残すための最低変更ルートではないからです。

その差はdocsにもcommunity frictionにも出ています。2026年3月27日時点 で、公式の互換画像例はまだ gemini-2.5-flash-image を使っていますが、native Geminiの画像docsはすでにGemini 3 image models中心です。forumでも、native image expectationsをcompatibility pathへ持ち込んだ結果、404やinvalid payloadに当たるケースが見えています。

実務上のルールは短くて十分です。

• 新規実装、cURL、raw REST、現行docsの追従なら native Gemini
• 既存のOpenAI-style stack維持が前提なら compatibility route
• 最初のdebugging roundで2つの契約を混ぜない

モデル、料金、ステータスで判断が変わるポイント

REST syntaxが正しくても、implementation choiceが正しいとは限りません。model lane、preview status、billing、limitの前提で答えが変わります。

Googleの billingページ は、新しいaccountsがFree Tierから始まり、free limits内で使えるmodelは一部に限られると説明しています。rate-limitsページ は、limitsがusage tier依存で、実際のactive limitはAI Studioで見るべきだと明記しています。

だからこのページでは “完全無料のGemini image REST API” とは言いません。requestが正しくても、model access、project tier、preview-limit policyのどれかが原因で失敗することは普通にあります。

Troubleshooting: どのレイヤーが壊れているかを先に切り分ける

このkeywordには最初からtroubleshooting intentが含まれています。多くの人は最初の失敗の後で検索してきます。幸い、よくあるfailure patternはかなり繰り返しです。

最も時間を節約できるのは、一度に一つの層しか変えないことです。host、model、prompt、save logicを同時に変えないでください。まずnative request、次にsave step、その後にquotaやcompatibility behaviorを見る順番が安全です。

もし問題がすでにURL選択を越えて429、400、500修正に入っているなら、次は Gemini API error fix 2026: 429, 400, 500 を見た方が早いです。

FAQ

/v1beta/openai/images/generations は間違ったパスですか

間違いではありません。既存の OpenAI-style client surface をそのまま保ちたいときには合理的な選択です。ただし、このキーワードで最初に知るべき default ではありません。新しい raw REST 実装なら、まず native generateContent を通してから互換ルートを比較する方が切り分けが速くなります。

なぜ成功したはずなのに JSON しか返ってこないのですか

native Gemini の画像 REST では、それが正常です。画像データは JSON の inlineData に入って返ってくるので、まだ最後の保存処理が終わっていないだけです。.inlineData.data を取り出して base64 decode し、画像ファイルとして書き出してください。

現在の default model はどれですか

まずは gemini-3.1-flash-image-preview から始めるのが安全です。現在の native image docs と models page が一番自然に指しているラインだからです。文字の多いポスターや図版など、最初の失敗コストが高い場面では gemini-3-pro-image-preview を検討します。互換サンプルでまだ見かける gemini-2.5-flash-image には、Google が 2026年10月2日 の shutdown date を示しています。

AI Studio では動くのに cURL で失敗するとき、最初に何を見ますか

まず URL を疑う前に、同じ project、同じ API key、同じ model access で呼んでいるかを確認します。そのうえで billing、tier、live limits を見ます。REST syntax の問題に見えても、実際には project context の差が原因というケースはかなり多いです。

結論

現在のraw HTTP image generationなら、まずnative Gemini Developer APIから始めます。

text
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent

responseModalities と imageConfig を使い、返ってきた inlineData を保存し、それでもOpenAI-style client surfaceを維持する必要がある場合にだけ /v1beta/openai/images/generations を検討します。

これが最も安全なcurrent defaultです。理由は、現行のnative Gemini docsと一致し、画像契約を最も分かりやすく保ち、このkeywordで最も多い誤解、つまり OpenAI互換画像パスをGemini image REST全体のuniversal defaultだと思ってしまうことを避けられるからです。