# Nano Banana 2.1 — /images/generations

Google Nano Banana 2.1（2026 年 10 月に公開された Nano Banana 2 の改良版）による画像生成 API（非同期ジョブ）です。テキストからの生成は prompt だけで済み、編集は参照画像を image または images（URL、data:、base64）に入れるか /v1/images/edits を呼びます。送信するとすぐにジョブ id（HTTP 202）が返り、GET /v1/images/jobs/{id} をポーリングして画像を受け取ります。1:1、3:4、2:3、9:16、4:3、3:2、16:9 などの比率と 1K / 2K / 4K に対応し、4:1、1:4、8:1、1:8 の横長・縦長もそのまま生成できます。1 枚単位の課金で、失敗したリクエストは課金されません。

**エンドポイント:** `POST https://nezhagate.com/v1/images/generations`

## クイックスタート

3 ステップで動きます：ジョブを送信 → 結果を照会 → 画像リンクを受け取る。YOUR_API_KEY をご自身のキーに置き換えれば、下のコマンドはそのまま実行できます。

ステップ 1 · 送信（すぐにジョブ ID を返します。HTTP 202）

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "16:9", "resolution": "2K"}'
```

レスポンス（HTTP 202）

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281500,
  "model": "nano-banana-2.1"
}
```

ステップ 2 · status が succeeded か failed になるまで 2〜3 秒ごとに照会

```bash
curl https://nezhagate.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功時のレスポンス

```json
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281500,
  "model": "nano-banana-2.1",
  "data": [
    {"url": "https://img.nezhagate.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "nano-banana-2.1"}
}
```

ステップ 3 · data[0].url が画像（PNG）です。保存期間は 60 日なので、長く使う場合はご自身のストレージにダウンロードしてください。

### 完全なサンプル（Python：送信 → 待機 → ローカルに保存）

```python
import time
import requests

BASE = "https://nezhagate.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 送信
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "nano-banana-2.1",
    "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 終わるまで 3 秒ごとに照会
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 画像をダウンロード
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("nano-banana-2.1.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["message"])
```

## 認証
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## リクエストボディ
| パラメータ | 種別 | 必須 | 説明 |
| --- | --- | --- | --- |
| `model` | string | はい | モデル ID。ここでは nano-banana-2.1 です。 |
| `prompt` | string | はい | 画像を説明するテキストプロンプト。 |
| `size` | string | いいえ | 出力の画面比率。1:1、3:4、2:3、9:16、4:3、3:2、16:9 のいずれかの比率を渡すのがおすすめで、モデルはその比率でネイティブに描画するため被写体が切れません。ピクセル指定（1024x1024、1024x1536、1536x1024 など）も受け付けます。既定は 1:1（正方形）です。 |
| `resolution` | string | いいえ | 解像度のグレード：1K（既定）/ 2K / 4K で、グレードごとに課金します。size の比率と組み合わせて使います（例：{"size": "16:9", "resolution": "2K"}）。グレードごとの実際のピクセル数は下の「比率・解像度・出力サイズ」にあります。size にピクセルサイズ（例：2048x1152）を書いた場合は、長辺でグレードが決まります。 |
| `n` | integer | いいえ | 常に 1：1 つのジョブで 1 枚を生成します。大きな値を指定しても 1 枚だけが返り、1 枚分だけ課金されます。複数枚ほしい場合は複数のジョブを同時に送信してください。 |
| `image` | string | いいえ | 画像から画像：参照画像を公開 URL、data: URI、生の base64 のいずれかで渡します。指定すると、人物や被写体を保ったままの本物の画像から画像として、選んだサイズ・比率で生成します。/v1/images/edits の呼び出しと同等です。 |
| `images` | array | いいえ | 複数の参照画像、最大 8 枚（それ以上送ると先頭の 8 枚だけを使います）：文字列の配列、または {"image_url": "..."} オブジェクトの配列。各画像は公開 URL、data: URI、base64 のいずれかで、1 枚 16MB まで。指定すると画像から画像になり、/v1/images/edits と同じです。1 枚だけなら上の image フィールドも使えます。 |

## リクエスト例
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "nano-banana-2.1", "prompt": "a serene ink-wash poster, lots of negative space", "size": "16:9", "resolution": "2K"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## レスポンス
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "nano-banana-2.1"
}
```

## 料金

画像 1 枚ごとの課金で、料金は解像度のグレードだけで決まり、比率やテキストから画像 / 画像から画像の違いは関係ありません。送信時にグレードの料金を確保し、ジョブが失敗した場合は全額返金します。1 クレジット = $0.005。

| グレード | 1 枚あたりのクレジット | 1 枚あたりの料金（USD） |
| --- | --- | --- |
| 1K | 3 | $0.015 |
| 2K | 5 | $0.025 |
| 4K | 8 | $0.04 |

1 つのジョブで生成されるのは常に 1 枚です。n に何を指定しても 1 枚が返り、1 枚分だけ課金されます。複数枚ほしい場合は複数のジョブを同時に送信してください（1 アカウントで同時に 50 枚まで生成できます）。

## 比率・解像度・出力サイズ

size に比率を、resolution にグレード（既定 1K、2K、4K）を指定します。モデルは選んだ比率で直接描画し、正方形を描いてから切り抜くことはしません。納品される画像は長辺が 1024 / 2048 / 4096 ピクセルで、もう一辺は比率で決まります。よく使う比率：

| 比率 | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 4096x4096 |
| 3:4 | 768x1024 | 1536x2048 | 3072x4096 |
| 2:3 | 683x1024 | 1365x2048 | 2731x4096 |
| 9:16 | 576x1024 | 1152x2048 | 2304x4096 |
| 4:3 | 1024x768 | 2048x1536 | 4096x3072 |
| 3:2 | 1024x683 | 2048x1365 | 4096x2731 |
| 16:9 | 1024x576 | 2048x1152 | 4096x2304 |

この 7 種類のほか、4:5、5:4、21:9、1:4、4:1、1:8、8:1 もネイティブに描画します（長辺のルールは同じ）。それ以外の比率は、いちばん近い横長・縦長・正方形で描いてから指定の比率に切り抜くため、画面の一部が切れることがあります。

size にはピクセルサイズ（例：1536x1024）も書けます。その場合は書いたとおりのサイズで納品し、グレードは長辺で決まります（1536 以下は 1K、2048 以下は 2K、それより大きいと 4K）。resolution は 1K / 2K / 4K（大文字小文字は不問）だけを受け付け、それ以外の値は無視されてグレードは size から決まります（既定は 1K）。size を省略すると 1:1 の正方形になります。

## 画像から画像と参照画像

- image（1 枚）または images（複数枚、最大 8 枚。それ以上送ると先頭の 8 枚だけを使います）を渡すと画像から画像になります。何をどう変えるかはプロンプトに書いてください。POST /v1/images/edits も同じパラメータで使えます。
- 参照画像は公開された画像 URL（http / https）、data: URI、またはそのままの base64 で、1 枚 16MB まで、JPEG・PNG・WebP などの一般的な形式に対応します。
- URL は画像そのものをダウンロードできる必要があります（Web ページ、ログインが必要な URL、直リンク禁止の URL は不可）。読み込めない参照画像は送信時に 400 と理由を返し、ジョブは作られず課金もされません。
- 出力の比率は参照画像ではなく size で決まります。元の比率を保ちたい場合は size を元画像と同じ比率にしてください。
- 参照画像は当サイトで代わりにホストし、7 日間保存します。

**参照画像 2 枚で画像から画像**

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## ジョブの状態と返却フィールド

GET /v1/images/jobs/{id} は常に id、object（image.generation.job）、status、created（Unix 秒）、model を返し、そのほかのフィールドは状態によって付きます。

| status | 意味 | 追加されるフィールド |
| --- | --- | --- |
| `queued` | 待機中 | queue_position（前にあるジョブの数）、eta_seconds（待ち時間の目安、秒） |
| `processing` | 生成中 | — |
| `succeeded` | 完了 | data[].url（画像リンク。当サイトの画像ホストで 60 日間保存）、usage.images（納品枚数）、usage.resolution（課金グレード） |
| `failed` | 失敗（送信時に確保した料金は全額返金済み） | error.message、error.type、error.code |

照会は 2〜3 秒ごとがおすすめです。1 アカウントで同時に生成できるのは 50 枚までで、それを超えるジョブは送信順に待機します。15 分待っても開始されないジョブは自動的に失敗となり、全額返金されます。ジョブの記録は 3 日間保存され、その後はジョブ ID で照会すると 404 になりますが、画像リンクは 60 日間有効です。ジョブは送信したアカウントからしか照会できません。

## 生成にかかる時間

送信から結果までの一般的な所要時間です（目安）。画像から画像はテキストから画像より数秒〜十数秒長くかかり、別の回線で再実行されたジョブは 1〜2 分かかることがあります。

| グレード | 所要時間の目安 |
| --- | --- |
| 1K | 25–40 秒 |
| 2K | 25–50 秒 |
| 4K | 35–80 秒 |

## エラーと返金

エラーはすべて {"error": {"message", "type", "code", "param"}} という同じ形式です。code で分岐してください。

### 送信時に返るエラー（ジョブは作られず、課金もされません）

| HTTP | code | 原因 | 対処 |
| --- | --- | --- | --- |
| 400 | `missing_prompt` | prompt が空 | prompt を入れる |
| 400 | `model_not_found` | model の ID が誤っているか、現在利用できない | ID を確認（利用可能なモデルは /v1/models） |
| 400 | `invalid_request` | 参照画像を読み込めない（リンク切れ、画像ではない、16MB 超など）。どの画像かと理由は message に記載 | 画像の直リンクを使うか base64 で送る |
| 401 | `invalid_api_key` | キーが誤っている、削除済み、または無効 | コンソールでキーを確認 |
| 402 | `insufficient_quota` | 残高がこのジョブの確保額に足りない | チャージして再試行 |
| 429 | `rate_limit_exceeded` | このキーに設定した 1 分あたりの上限を超えた | 頻度を下げるか、コンソールでキーの上限を上げる |
| 503 | `model_maintenance` | モデルがメンテナンス中 | しばらくして再試行（ステータスページを参照） |
| 503 | `service_unavailable` | 当サイト側の一時的なエラー（参照画像の保存失敗など） | 少し待って再試行 |

### 失敗したジョブ（受け付け後に status が failed で終了。確保した料金は全額返金）

| 状況 | 表示される内容 | 対処 |
| --- | --- | --- |
| プロンプトか参照画像が Google の安全審査を通らなかった | error.message に Content blocked などの審査メッセージ | プロンプトを書き換えるか参照画像を変える。そのまま再送信してもたいてい再び拒否されます |
| 生成回線の一時的な障害やタイムアウト（先に別の回線で自動的に再試行し、すべて失敗したときだけ失敗を返します） | error.code が upstream_error や upstream_timeout など。理由は message に記載 | そのまま再送信 |
| 15 分待っても開始されなかった | error.message にその旨 | しばらくして再送信 |

## ポーリングの代わりに Webhook を使う

本番環境では、送信時に callback_url を付けることをおすすめします。ジョブが終わると（成功でも失敗でも）、照会エンドポイントと同じ JSON をその URL に image.completed または image.failed として POST し、送信元を検証できる署名ヘッダーも付けます。「設定 → Webhook」でアカウント全体の URL を設定することもできます。 [Webhook ドキュメント](https://nezhagate.com/ja/docs/webhooks)

```bash
curl https://nezhagate.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nano-banana-2.1", "prompt": "An orange cat on a windowsill watching the rain, warm desk lamp, cinematic, shallow depth of field", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```