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

> Gemini画像生成REST APIの現在の正しい呼び方を整理します。まずnative GeminiのcURLを通し、返ってきた画像を保存し、そのあとでOpenAI互換ルートを検討します。

- Source: https://www.aifreeapi.com/ja/posts/gemini-image-generation-rest-api
- Language: ja
- Published: 2026-03-27
- Updated: 2026-10-08
- Publisher: AI Free API (https://www.aifreeapi.com)

> **2026年10月8日訂正：** Googleは`gemini-2.5-flash-image`の提供終了日を当初の2026年10月2日から2027年3月15日に延期し、移行先を`gemini-3.1-flash-lite-image`（Nano Banana 2 Lite）に変更しました。本文中の「10月2日に終了」という記述は現在は当てはまりません。

**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の答えが今でも複数ページに分散しているからです。[画像生成ガイド](https://ai.google.dev/gemini-api/docs/image-generation) はnative Geminiの流れを説明し、[API reference](https://ai.google.dev/api/generate-content) は `generateContent` と `imageConfig` の契約を定義し、[OpenAI compatibility docs](https://ai.google.dev/gemini-api/docs/openai) は別の互換ルートを示します。これらをまとめて読むと、どれも同じ「最初の答え」に見えがちですが、新しい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の問題とモデルの問題を混同しやすくなります。

![Gemini画像生成REST APIガイド。native generateContentルート、現在のモデル選択、cURLワークフローを示している。](https://www.aifreeapi.com/posts/ja/gemini-image-generation-rest-api/img/cover.png)

## 要点まとめ

| 状況 | 最初に使うパス | まず選ぶモデル | これが現在のdefaultである理由 | 主な caveat |
| --- | --- | --- | --- | --- |
| 新規のraw REST統合 | `POST /v1beta/models/gemini-3.1-flash-image-preview:generateContent` | `gemini-3.1-flash-image-preview` | 現行のnative Gemini画像ドキュメントと最も一致し、`imageConfig` を直接使える | Gemini 3画像モデルはまだpreview |
| 文字入り画像や高価値なビジュアル | 同じnative `generateContent` | `gemini-3-pro-image-preview` | premium branchとして使いやすい | コストが高く、こちらもpreview |
| 既存のOpenAI風clientを維持したい | `POST /v1beta/openai/images/generations` | 互換ドキュメントが現在サポートするsurfaceを確認 | クライアント変更を最小化できる | native Geminiのdefaultではなく別契約 |
| AI Studioでは動くのにcURLでは失敗する | URLだけの問題ではないことが多い | 同じprojectとmodelを確認 | billing、tier、accessの差が原因になりやすい | すべてのユーザーに共通の固定limit表は公開されていない |

hostとpathの切り分けだけ知りたいなら [Gemini画像生成APIのBase URL](/ja/posts/gemini-image-generation-api-base-url) が先です。SDK例も含めて見たいなら [Gemini画像生成コード例](/ja/posts/gemini-image-generation-code-examples) が次に合います。

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

![native Gemini generateContentスタックをdefault REST pathとして示し、モデル選択とcompatibility contextを二次的に扱うルーティング図。](https://www.aifreeapi.com/posts/ja/gemini-image-generation-rest-api/img/native-route-stack.png)

新しい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ページ](https://ai.google.dev/gemini-api/docs/models) はこれを現行の高効率画像ラインとして見せていて、`gemini-3-pro-image-preview` はpremium branchとして残しています。旧ラインの `gemini-2.5-flash-image` もまだ存在しますが、Googleの [deprecationsページ](https://ai.google.dev/gemini-api/docs/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](https://ai.google.dev/api/generate-content) では、`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](/ja/posts/gemini-image-generation-api-pricing) の方が役に立ちます。

## REST responseから画像を保存する

![Gemini画像REST request、返却されるinline image data、そしてdecode-to-file保存手順を示すフロー図。](https://www.aifreeapi.com/posts/ja/gemini-image-generation-rest-api/img/request-response-flow.png)

多くの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](https://ai.google.dev/gemini-api/docs/openai) には次の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の前提で答えが変わります。

| モデル | 現在の役割 | 使う場面 | caveat |
| --- | --- | --- | --- |
| `gemini-3.1-flash-image-preview` | 新しいraw RESTのdefault | 多くのcurrent image generation / editing | まだpreview |
| `gemini-3-pro-image-preview` | premium branch | レイアウト、文字描画、高価値visualが重要 | コストが高く、これもpreview |
| `gemini-2.5-flash-image` | 旧lineだが互換例でまだ見かける | 古いexamplesや意図的なmigration context | Googleは **2026年10月2日** のshutdown dateを出している |

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

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

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

![Gemini画像RESTワークフローで404、無効payload、project mismatch、画像decode漏れをどう切り分けるかを示すトラブルシューティング図。](https://www.aifreeapi.com/posts/ja/gemini-image-generation-rest-api/img/rest-error-triage-map.png)

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

| 見えている現象 | よくある実際の原因 | 次にやること |
| --- | --- | --- |
| `/v1beta/openai/images/generations` で404 | compatibility route上でmodelやrequest shapeが合っていない | 同じ処理をnative Gemini `generateContent` で試す |
| `Unknown name "generationConfig"` あるいは `generation_config` | native Gemini fieldをOpenAI互換契約へ送っている | nativeへ戻すか、互換schemaへ完全に寄せる |
| 古いimage modelで `model not found` | 古いsnippetやforumのmodel IDをコピーした | current modelsとdeprecationsを再確認する |
| AI Studioでは動くのにcURLでは失敗 | API key、billing、project accessがbrowser contextと違う | 同じproject、key、modelを照合する |
| JSONは返るが画像ファイルがない | request自体は成功していて、`inlineData` のdecodeが終わっていない | `.inlineData.data` を取り出してbase64 decodeする |

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

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

## 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だと思ってしまうことを避けられるからです。