> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bettertoken.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana API：画像生成・参照画像・連続編集

> BetterToken で Nano Banana Pro・2・2.1 を利用する手順。認証、解像度、Python、参照画像の送信、画像保存、連続編集、パラメーター制限を説明します。

同じ Gemini ネイティブ接続先で、文章からの生成、参照画像の編集、追加編集を行えます。例は `nano-banana-2.1` を使用します。他の 2 モデルは URL または SDK のモデル ID を置き換えてください。

* [Gemini テキスト画像生成 API](/ja/api-reference/gemini-images-generations)
* [Gemini 画像編集 API](/ja/api-reference/gemini-images-edits)

<Warning>
  BetterToken API は Google のウェブ検索や画像検索を利用した画像生成に対応していません。検索ツールを追加しないでください。
</Warning>

## 接続情報

| 項目 | 設定 |
| - | - |
| Base URL | `https://bettertoken.ai` |
| リクエスト | `POST /v1beta/models/{model}:generateContent` |
| 認証 | `x-goog-api-key: YOUR_API_KEY` または `Authorization: Bearer YOUR_API_KEY` のいずれかを使用します。 |
| 本文 | `application/json` |
| Model ID | `nano-banana-pro`, `nano-banana-2`, `nano-banana-2.1` |

<a href={"https://bettertoken.ai/register"}>BetterToken API Key を作成</a> · <a href={"https://bettertoken.ai/pricing"}>モデルカタログ</a> · [Nano Banana モデル紹介](/ja/model-updates/nano-banana)

<Warning>
  3 モデルは `POST /v1/images/generations` と `POST /v1/images/edits` に対応せず、`400 unsupported_endpoint` を返します。GPT Image の multipart、`image[]`、`data[].b64_json` の例は使用しないでください。
</Warning>

## 最初の画像を生成する

ターミナルで `BETTERTOKEN_API_KEY` を設定して実行します。生成を待ち、JSON 全体を `response.json` に保存します。

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    export BETTERTOKEN_API_KEY="YOUR_API_KEY"

    curl --fail-with-body --max-time 650 \
      "https://bettertoken.ai/v1beta/models/nano-banana-2.1:generateContent" \
      -H "x-goog-api-key: $BETTERTOKEN_API_KEY" \
      -H "Content-Type: application/json" \
      -H "X-BetterToken-Max-Images: 1" \
      -d '{
        "contents": [{
          "role": "user",
          "parts": [{"text": "白いテーブルに置いた青い陶器のマグカップのスタジオ商品写真。"}]
        }],
        "generationConfig": {
          "responseModalities": ["IMAGE"],
          "candidateCount": 1,
          "imageConfig": {"imageSize": "1K", "aspectRatio": "1:1"}
        }
      }' -o response.json
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $env:BETTERTOKEN_API_KEY = "YOUR_API_KEY"
    $headers = @{
        "x-goog-api-key" = $env:BETTERTOKEN_API_KEY
        "X-BetterToken-Max-Images" = "1"
    }
    $body = @{
        contents = @(@{
            role = "user"
            parts = @(@{ text = "白いテーブルに置いた青い陶器のマグカップのスタジオ商品写真。" })
        })
        generationConfig = @{
            responseModalities = @("IMAGE")
            candidateCount = 1
            imageConfig = @{ imageSize = "1K"; aspectRatio = "1:1" }
        }
    } | ConvertTo-Json -Depth 10
    Invoke-WebRequest `
        -Uri "https://bettertoken.ai/v1beta/models/nano-banana-2.1:generateContent" `
        -Method Post `
        -Headers $headers `
        -ContentType "application/json" `
        -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) `
        -TimeoutSec 650 `
        -OutFile "response.json"
    ```
  </Tab>
</Tabs>

高解像度が必要なら `imageSize` を `2K` または `4K` に変更します。最初は `1K`、`1:1`、1 枚から始め、`--retry` による自動再送は設定しないでください。

## 主なパラメーター

商品写真では被写体、材質、照明、背景を説明します。ポスターでは正確な文字と配置を指定します。編集では変更する部分と維持する部分を伝えます。

ネイティブ HTTP は下表、Python SDK は snake\_case を使います。画像設定は `generationConfig.imageConfig` 内に配置します。

| 項目 | 設定 |
| - | - |
| `contents[].parts[].text` | 被写体、背景、スタイル、変更点を説明します。 |
| `contents[].parts[].inlineData` | 元の参照ファイルの `mimeType` と base64。画像 URL ではありません。 |
| `generationConfig.responseModalities` | `["IMAGE"]` を明示します。 |
| `generationConfig.imageConfig.imageSize` | 大文字の `1K`、`2K`、`4K`。省略時は `1K`。 |
| `generationConfig.imageConfig.aspectRatio` | 下表からモデルに対応する比率を選択します。例は `1:1` です。 |
| `generationConfig.candidateCount` | 省略または整数 `1`。ネイティブのルートに `n` は指定しません。 |
| `X-BetterToken-Max-Images` | 任意ヘッダー。整数 `1`～`4`、既定値 `1`。受け取りと課金を許可する最大画像数。 |

<span id="aspect-ratios" />

### Google 公式の対応比率

Nano Banana 2 と 2.1 は 14 種類、Pro は 10 種類の比率に対応しています。最初のリクエストは `1:1` から始めてください。

| モデル | 解像度 | 比率 |
| - | - | - |
| `nano-banana-pro` | `1K`, `2K`, `4K` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
| `nano-banana-2` | `1K`, `2K`, `4K` | `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` |
| `nano-banana-2.1` | `1K`, `2K`, `4K` | `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9` |

[Google の比率と画像サイズの説明](https://ai.google.dev/gemini-api/docs/image-generation#aspect-ratios-and-image-size)

上限は枚数の保証ではありません。複数枚を指示しても 1 枚になる場合があります。固定枚数が必要なら別々にリクエストしてください。

## 応答から画像を保存する

画像は `candidates[].content.parts[].inlineData` にあります。下記は構造の例で、`BASE64_IMAGE_DATA` は仮の値です。最終画像の全 part を処理し、`thought: true` は除外してください。

```json theme={null}
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{
        "inlineData": {
          "mimeType": "image/jpeg",
          "data": "BASE64_IMAGE_DATA"
        }
      }]
    },
    "finishReason": "STOP"
  }]
}
```

次の Python で curl の結果を保存できます。拡張子は `mimeType` に合わせます。JPEG の可能性があるため、一律に `.png` としないでください。

```python theme={null}
import base64
import json
from pathlib import Path

suffixes = {"image/png": ".png", "image/jpeg": ".jpg"}
result = json.loads(Path("response.json").read_text())
saved = 0
for candidate in result.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        if part.get("thought"):
            continue
        blob = part.get("inlineData")
        if not blob:
            continue
        suffix = suffixes.get(blob["mimeType"])
        if suffix is None:
            raise ValueError("Unexpected image MIME type: " + blob["mimeType"])
        saved += 1
        Path(f"generated-{saved}{suffix}").write_bytes(
            base64.b64decode(blob["data"], validate=True)
        )
if saved == 0:
    raise RuntimeError("No final image returned; inspect response.json.")
```

## Python SDK の完全な例

Python 3.10 以降と `google-genai==2.30.1` を使います。プロジェクトの仮想環境にインストールしてください。古い SDK は `image_size` を送信しない場合があります。

```bash theme={null}
python -m pip install "google-genai==2.30.1"
```

SDK の Base URL はドメインのルートです。`/v1` や `/v1beta` を追加しません。`timeout` はミリ秒、`attempts=1` は自動再試行を無効にします。`save_images` は最終画像をすべて保存します。

```python theme={null}
import os
from pathlib import Path
from google import genai
from google.genai import types

MODEL = "nano-banana-2.1"
client = genai.Client(
    vertexai=False,
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://bettertoken.ai",
        api_version="v1beta",
        timeout=650_000,
        retry_options=types.HttpRetryOptions(attempts=1),
        headers={"X-BetterToken-Max-Images": "1"},
    ),
)
config = types.GenerateContentConfig(
    response_modalities=["IMAGE"],
    candidate_count=1,
    image_config=types.ImageConfig(image_size="1K", aspect_ratio="1:1"),
)

def save_images(response, prefix):
    if len(response.candidates or []) != 1 or not response.candidates[0].content:
        raise RuntimeError("No single image candidate returned.")
    saved = 0
    suffixes = {"image/png": ".png", "image/jpeg": ".jpg"}
    for part in response.candidates[0].content.parts or []:
        if part.thought or not part.inline_data:
            continue
        blob = part.inline_data
        suffix = suffixes.get(blob.mime_type)
        if suffix is None:
            raise ValueError("Unexpected image MIME type: " + str(blob.mime_type))
        saved += 1
        Path(f"{prefix}-{saved}{suffix}").write_bytes(blob.data)
    if saved == 0:
        raise RuntimeError("No final image returned; inspect the response.")

first_turn = types.Content(
    role="user",
    parts=[types.Part(text="白いテーブルに置いた青い陶器のマグカップのスタジオ商品写真。")],
)
response = client.models.generate_content(
    model=MODEL, contents=[first_turn], config=config,
)
save_images(response, "generated")
```

## 参照画像を送る

Python の例の後に実行すると、新たな編集リクエストになります。`reference.jpg` をローカルファイルに置き換えてください。PNG は `mime_type="image/png"`。複数の参照画像は同じユーザーメッセージの `parts` に追加します。

```python theme={null}
first_turn = types.Content(
    role="user",
    parts=[
        types.Part(text="マグカップを赤くしてください。形と背景は維持してください。"),
        types.Part.from_bytes(
            data=Path("reference.jpg").read_bytes(),
            mime_type="image/jpeg",
        ),
    ],
)
response = client.models.generate_content(
    model=MODEL, contents=[first_turn], config=config,
)
save_images(response, "reference-edit")
```

ネイティブ JSON は `inlineData: {"mimeType": "image/jpeg", "data": "BASE64_IMAGE_DATA"}` です。元のバイト列を base64 にし、`data:image/...;base64,` を付けません。multipart、Files、`fileData` は使用しません。

## 続けて編集する

生成または参照編集の成功後に実行します。モデル応答の `content` 全体と part の順序、`thoughtSignature` を保持してください。画像だけで履歴を再構築せず、署名を作成・変更しないでください。

```python theme={null}
history = [first_turn, response.candidates[0].content]
edit_turn = types.Content(
    role="user",
    parts=[types.Part(text="小さな金色の持ち手を追加し、それ以外は変えないでください。")],
)
edited = client.models.generate_content(
    model=MODEL, contents=[*history, edit_turn], config=config,
)
save_images(edited, "follow-up")
history.extend([edit_turn, edited.candidates[0].content])
```

各ターンは新しい生成です。完全な `history` にユーザー指示、返却されたモデル `content` の順に追加します。Interactions の `previous_interaction_id` は使用しません。

## API の対応範囲

* 非ストリーミングの `generateContent` を使用します。Files / `fileData`、Batch、Interactions、ストリーミングには対応していません。
* `responseMimeType`、`responseSchema`、画像圧縮形式の指定には対応していません。`imageConfig` は上記の 2 フィールドのみ使用してください。
* `cachedContent`、関数呼び出し、コード実行、ファイル検索、Maps、URL context、音声入力・生成の設定は追加しないでください。

## 既存の OpenAI Chat クライアントを使う

`POST /v1/chat/completions` と Base URL `https://bettertoken.ai/v1` を利用できます。新規接続、参照画像、連続編集には上記の Gemini ネイティブ API を推奨します。Chat の `n` は省略するか整数 `1` にしてください。

HTTP では `google.image_config` を JSON のルートに置きます。Python OpenAI SDK は `extra_body` をルートに統合します。ここでは `generationConfig` を使用しません。

```bash theme={null}
curl --fail-with-body --max-time 650 \
  "https://bettertoken.ai/v1/chat/completions" \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-BetterToken-Max-Images: 1" \
  -d '{
    "model": "nano-banana-2.1",
    "messages": [{"role": "user", "content": "白いテーブルに置いた青い陶器のマグカップ。"}],
    "n": 1,
    "stream": false,
    "google": {"image_config": {"image_size": "1K", "aspect_ratio": "1:1"}}
  }'
```

Python OpenAI SDK の例は同じ仮想環境に `openai==1.66.2` をインストールして実行します：

```python theme={null}
import base64
import os
import re
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["BETTERTOKEN_API_KEY"],
    base_url="https://bettertoken.ai/v1",
    max_retries=0,
    timeout=650,
)
response = client.chat.completions.create(
    model="nano-banana-2.1",
    messages=[{"role": "user", "content": "白いテーブルに置いた青い陶器のマグカップ。"}],
    n=1,
    stream=False,
    extra_headers={"X-BetterToken-Max-Images": "1"},
    extra_body={
        "google": {"image_config": {"image_size": "1K", "aspect_ratio": "1:1"}}
    },
)
content = response.choices[0].message.content or ""
images = re.findall(r"data:(image/(?:png|jpeg));base64,([A-Za-z0-9+/=]+)", content)
if not images:
    raise RuntimeError("No inline image in Chat response.")
for index, (mime, data) in enumerate(images, 1):
    suffix = ".png" if mime == "image/png" else ".jpg"
    Path(f"chat-{index}{suffix}").write_bytes(base64.b64decode(data, validate=True))
```

Chat の画像は `choices[0].message.content` 内の Markdown Data URL です。Images API の `data[]` ではありません。この文字列から署名履歴を再構築せず、ネイティブ編集を使ってください。

## よくあるエラー

| 症状 | 対処 |
| - | - |
| `401` / 無効な Key | Google ではなく BetterToken API Key を使用し、環境変数とヘッダーを確認。 |
| `404` / URL | Base URL はルート、`api_version="v1beta"`、公開 Model ID のいずれかを使用。 |
| `400 unsupported_endpoint` | `/v1/images/*` を `:generateContent` に変更。 |
| `400` / パラメーター | フィールド階層、`1K/2K/4K` の大文字、モデルの対応比率を確認します。`candidateCount` は省略または整数 `1` にし、検索ツールを追加しないでください。 |
| 最終画像がない | 応答全体のエラー、安全情報、テキスト、`finishReason` を確認。thought 画像は保存対象外。 |
| ファイルが開けない | base64 をデコードし MIME に合う拡張子を使用。JSON や Markdown 全体を保存しない。 |
| タイムアウト・切断 | 利用記録と応答のリクエスト ID を確認。再送前にサポートと結果を確認し、重複生成・課金を避ける。 |

画像は現在の応答で返ります。このフローに後からの画像取得やタスクのポーリングはありません。すぐ保存し、SDK とプロキシに十分な待機時間を設定して自動再試行を無効にしてください。

## 公式資料

* [Nano Banana Pro モデル](https://ai.google.dev/gemini-api/docs/models/gemini-3-pro-image)
* [Nano Banana 2 モデル](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-image)
* [Nano Banana 2.1 モデル](https://ai.google.dev/gemini-api/docs/models/gemini-nano-banana-2.1)
* [Google 画像生成ガイド](https://ai.google.dev/gemini-api/docs/generate-content/image-generation)
* [Google リリースノート](https://ai.google.dev/gemini-api/docs/changelog)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.