Gemini画像生成APIのBase URL: native Gemini と OpenAI互換URLの正しい使い分け

2026年3月24日時点で、Gemini画像生成の native な base URL は https://generativelanguage.googleapis.com/v1beta で、最初に試すべきパスは POST /models/gemini-3.1-flash-image-preview:generateContent です。 https://generativelanguage.googleapis.com/v1beta/openai/ を使うのは、OpenAI互換レイヤーを意図的に維持している場合だけです。

この検索語の本質はここにあります。Google の image generation docs、API reference、OpenAI compatibility docs はそれぞれ正しい情報を持っていますが、「Gemini の画像生成で何を default にすべきか」を一枚で答えてはくれません。

安全な進め方はシンプルです。まず native の generateContent を一回通し、本当に画像が返ることを確認する。そのあとで OpenAI 互換レイヤーが必要か、別モデルに切り替えるべきか、問題が quota 側にあるのかを判断します。広い背景まで確認したくなったら Gemini画像生成チュートリアル と Gemini画像生成コード例 を読む方が自然です。

最初に押さえるポイント:

• 新規の Gemini image generation は https://generativelanguage.googleapis.com/v1beta から始める。
• 最初の完全パスは /models/gemini-3.1-flash-image-preview:generateContent を優先する。
• https://generativelanguage.googleapis.com/v1beta/openai/ は OpenAI 互換 client を保つときだけ使う。

要点まとめ

覚えるべき default は一つです。新しい Gemini 画像生成は native Gemini から始める。これが最も安全です。

実務ではもう一段だけ順番を固定するとさらに迷いません。まず host と model path を確定し、その後で image controls、quota、互換レイヤーの必要性を切り分ける。この順序にしておくと、「全部 base URL の問題に見える」状態を避けやすくなります。

native Gemini 画像生成ではこの base URL を使う

Gemini の公式 API reference は、現在も画像生成を generateContent の中で説明しています。だからこそ、昔ながらの /images/generations 型 endpoint を想像していると少し分かりにくく感じます。native Gemini では、host は通常の Gemini Developer API host のままで、画像生成かどうかは model path と generateContent の組み合わせで決まります。

ベースはこれです。

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

そして多くの開発者が最初に試すべき完全な画像生成パスはこれです。

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

現在の公式 docs は gemini-3.1-flash-image-preview を fast default として扱い、gemini-3-pro-image-preview を premium branch として扱っています。だからこのページでも、古い 2.5 時代の画像例から入ることは勧めません。新しい統合で本当に大事なのは、「今 Google が何を current path として教えているか」です。

もう一つ重要なのは feature surface です。imageSize、aspectRatio、画像編集、multi-turn のような image-native な制御は、native route の方がずっと理解しやすいです。Gemini の画像機能を今の形で使いたいなら、まず native host を基準にする方が迷いません。

/v1beta/openai/ を使うべきなのはどんなときか

OpenAI 互換の base URL は正式なものです。Google は今も次の URL を案内しています。

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

では、いつそれが正しい答えになるのでしょうか。答えは明確です。すでに OpenAI-style の SDK や wrapper を持っていて、client surface を大きく変えたくないときです。その前提があるなら互換レイヤーを選ぶ意味があります。

ただし、それを Gemini image generation 全般の default answer にしてしまうのは危険です。Google 自身も、OpenAI libraries を使っていないなら Gemini API を直接呼ぶ方を勧めています。画像ではこの違いが特に効きます。互換 docs では画像生成を主に gemini-2.5-flash-image と gemini-3-pro-image-preview で説明し、documented されていない追加パラメータは silently ignored される可能性があるとも書いています。

ここが混乱の中心です。互換 URL が valid であることと、それが今のあなたにとって最良の default であることは別です。native image controls を使いたいなら、または current Gemini docs の一番素直な流れに乗りたいなら、最初は native route に戻した方が安全です。

判断を単純化するとこうです。

• 新規実装、raw REST デバッグ、現行 Gemini docs 追従なら native。
• OpenAI-based stack を意図的に維持したいなら compatibility。
• 両方を同じデバッグセッションで混ぜない。

まずは動く REST request を一つコピーする

最初から複雑な workflow にしないでください。host と model と画像返却が通ることをまず証明します。

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 hero image of a matte black travel mug on a light concrete surface with soft studio lighting."
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'

この request が useful なのは、host、model、native image controls の三つを一度に検証できるからです。もし premium branch が必要なら model path を次に切り替えます。

text
/models/gemini-3-pro-image-preview:generateContent

文字入り画像の品質、より重い構図、より高価値な asset が本当に差を生むときだけ、こちらに上げる意味があります。次に知りたいことが URL ではなくコストなら Gemini image generation API pricing の方が合っています。

Troubleshooting

画像生成の失敗を全部 base URL のせいにしてはいけません。最近の forum thread を見ると、404、model not found、ignored parameters が出た瞬間に host 全体が間違っていると決めつけるケースが多いですが、実際の原因はもっと細かいことが多いです。

ここで見落としやすいのは quota です。Google の rate limits docs は、limit が API key 単位ではなく project 単位で評価されること、requests per day が Pacific time の深夜に reset されること、preview models の制限がより厳しいことを明記しています。つまり URL が正しくても、project 側の条件で失敗し得ます。

もう一つの落とし穴は compatibility behavior です。Google forum には、OpenAI-compatible image request で 404 が出る一方、同じ発想を native generateContent に移すと通るという話が出ています。ここから学ぶべきなのは「compat docs は無意味」ということではなく、「まず native route を証明し、互換レイヤーは migration layer として扱う方が安全」という順序です。

もしもう URL の問題を超えて 429、400、500 の修復段階に入っているなら、次は Gemini API error fix 2026: 429, 400, 500 を見た方が早いです。

最初の request の前に確認すること

チームで同じ議論を何度も繰り返さないためには、最初の image request の前に前提を固定しておく方が有利です。base URL の混乱は、文書が一切足りないから起こるというより、違う host、違う model、違う project context を同時に比較してしまうことで増幅されることが多いです。

まず Gemini Developer API と Vertex AI を切り分けます。ここが曖昧なままだと、404 も model not found も全部「host が間違っているのでは」という話に見えてしまいます。次に、一回目の検証では host を一つ、model を一つ、認証方法を一つに固定します。?key= と x-goog-api-key を同時に変えたり、native と compatibility を同じ回で行き来したりしない方が結果を読みやすくできます。

さらに、一度通った完全な endpoint はそのまま runbook やプロジェクト文書に残しておくべきです。多くの現場で時間を奪うのは新しい難問ではなく、誰かが古い example や forum の断片を貼り直して、検証済みの path がチーム内で共有されていないことです。

最後に、proxy、SDK wrapper、retry、compatibility abstraction は native request が安定して画像を返した後で足します。この順序にしておくと、どの層から不具合が入ったのかを追いやすくなり、URL 全体を疑う必要がある場面がかなり減ります。

Gemini Developer API と AI Studio と app を混同しない

この keyword がややこしいのは、Google が関係のある別 product を同じ search results に出してくるからです。

Gemini Developer API が generativelanguage.googleapis.com host の本体です。このページが答えているのはその contract です。

AI Studio は API に近い UI / project surface ですが、そこに見えている挙動をそのまま API contract と考えるべきではありません。billing、project、model availability は依然として別の論点です。Google の billing FAQ は paid API key を紐づけるまでは無料利用が残ると説明していますが、それでも native image request に使うべき host 自体は変わりません。

Gemini app はさらに base URL の質問から離れています。手動で画像を作るには便利ですが、app の挙動はコードが呼ぶ API contract そのものではありません。だから product boundary を理解する手助けにはなっても、endpoint の答えそのものにはなりません。

もし実際には Vertex AI を使っているなら、そこは最初に切り分けるべきです。Vertex AI には独自の endpoint family があり、Gemini Developer API host をそのまま持ち込むと最初からデバッグの層を間違えます。

結論

今の Gemini Developer API で画像生成をするなら、default answer は:

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

そして最初に試すべき path は:

text
/models/gemini-3.1-flash-image-preview:generateContent

次の URL に切り替えるのは:

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

を本当に必要とする OpenAI-compatible stack のときだけです。

この順序が最も安全なのは、現行の native Gemini docs と一致し、画像機能の contract を最も分かりやすく保ち、この検索語の裏にある一番多いミスを避けられるからです。つまり、OpenAI 互換 host を Gemini の画像 request 全般の universal default だと思い込まないことです。

チーム向けに一文で要約するなら、「最初にコードへ入れるのは native host、最初に試すのは gemini-3.1-flash-image-preview:generateContent、互換 URL は OpenAI 系 client を残すと決めた後にだけ検討する」で十分です。