> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Nano Banana シリーズ開発者ガイド
> Nano Banana シリーズ（Pro / 2 / 2 Lite / Gen 1）におけるモデル選定、課金、エンドポイント、開発形式、FAQ を一括で確認できるガイドです。開発者が Gemini 画像生成 API をすばやく使い始められるようにします。
## モデルカード
| Model | 公式モデルID | Billing | 備考 |
| ----------------------- | -------------------------------- | ----------------------------------------------------------------------- | --------------- |
| **Nano Banana Pro** | `gemini-3-pro-image-preview` | リクエストごとの固定 **\$0.09/req**（約 ¥0.63；チャージキャンペーン後は約 ¥0.55） | 最高品質 |
| **Nano Banana 2** | `gemini-3.1-flash-image-preview` | リクエストごとの **\$0.055/req**（4K出力に推奨）；または動的な token ベース課金で、2K は約 **\$0.04** | 最もコストパフォーマンスが高い |
| **Nano Banana 2 Lite** | `gemini-3.1-flash-lite-image` | リクエストごとの固定 **\$0.025/req**；または token ベース課金で約 **\$0.018/req**（公式価格の 40%） | 最速・最安、1K のみ |
| **Nano Banana** (Gen 1) | `gemini-2.5-flash-image` | リクエストごとの固定 **\$0.02/req** | 最安 |
完全な価格比較、リクエストごとの課金と token ベース課金の違い、token の選び方については、[Nano Banana Series Pricing](/ja/api-capabilities/nano-banana-pricing) をご覧ください。
### サイズ制御
* **元画像の比率に従う**: `aspectRatio` を単純に省略します。複数画像編集のシナリオでは、**最後の画像のサイズ** が優先されます
* **解像度 `imageSize`**: `1K` / `2K` / `4K` に対応
* Nano Banana (Gen 1) は **1K のみ対応**
* Nano Banana 2 は **512px を追加**
* Nano Banana 2 Lite は **1K のみ対応**（2K/4K/512px は非対応）
同じコードで初代 `gemini-2.5-flash-image` を呼び出す場合は、**`imageSize` パラメータを削除する必要があります**（`2K` / `4K` をサポートしていないため）、さもないと呼び出しは失敗します。
## 組み込み方法
### 公式ドキュメント
* Google 公式ドキュメント: `ai.google.dev/gemini-api/docs/image-generation`
* APIYI と連携するには、**request URL + KEY を APIYI のものに置き換える**だけです。その他のパラメータは公式のものとすべて同一です
### 公式ステータスの確認（上流障害の診断）
Nano Banana シリーズは Google の AIStudio / Gemini API 上で動作しています。まれに、**2K / 4K 出力がぼやける、または失敗する**問題は、統合レイヤーではなく **Google 側** に原因がある場合があります。Google の公式ステータスページを確認してください（URL をコピーしてご自身でアクセスしてください）: `aistudio.google.com/status`。
たとえば、2026年6月19日には、そのページで「Issues with Nano Banana」と報告されていました。Gemini API と AI Studio 上の Nano Banana 2 / Pro において、2K または 4K 解像度で問題が発生していました。同様の症状が見られる場合は、まず公式ステータスページと照合し、上流の障害かどうかを素早く判断してください。
APIYI は冗長化のため、**AIStudio + Vertex のデュアルチャネル** で Nano Banana シリーズを提供しています。片方の公式チャネルに問題が発生しても、もう一方が引き継いでサービスの可用性を維持できます。
### エンドポイント対応
* **推奨エンドポイント**（Gemini ネイティブ）: `https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent`
* **OpenAI 互換モード** 経由の呼び出しに対応しています（注: **URL アップロードはサポートされていません**。代わりに Base64 を使用してください）
* **対応していません** `/v1/image/generations`
### 開発形式（デフォルトの推奨）
* **\[推奨] Google ネイティブのエンドポイント形式を使用してください**
* 画像: **Base64 としてアップロードし、ダウンロードして再ホストする**
* 呼び出し方法: **同期マルチスレッド呼び出し**。非同期呼び出しはまだサポートされていません
## 入力画像の要件
* **単一の画像は 7MB を超えられません**（Google のルールです）。Google Cloud Storage 経由でインポートする場合、1ファイルあたりの上限は 30MB です
* **1 プロンプトあたり最大 14 枚の画像**
* **対応 MIME タイプ**: `image/png`, `image/jpeg`, `image/webp`, `image/heic`, `image/heif`（`jpg` 形式はすでに APIYI でサポートされています）
* **Base64 のサイズ増加**: 画像を Base64 に変換すると、サイズは約 **33.3%** 増加します（7MB の画像は約 9.3MB になります）
* **APIYI の制限**: 1 回のリクエストでアップロードされる画像の総量は **100MB 未満** である必要があります。すべての呼び出しは同期であり、サイズの大きすぎるペイロードはメモリ使用量の急増を引き起こす可能性があります
**ベストプラクティス**: API に送信する前に画像へ **可逆圧縮** を適用し、過剰な解像度によってリクエストが遅くなるのを避けてください。
Google 公式仕様の参照（コピーしてご自身でアクセスしてください）: `docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-pro-image`
## URL画像入力
Base64に加えて、**Geminiネイティブエンドポイント**では、画像URL（画像ホスト / OSSアドレス）を`fileData.fileUri`を通じて直接渡すこともでき、ローカルでのエンコードが不要です。
**URLアップロードは画像ホストとOSSアドレスに厳しい要件があります**: アドレスがグローバルCDN上にない場合（たとえば、Tencent Cloud Object Storage の既定は中国国内のみのCDNです）、Googleのサーバーが画像に到達できない可能性が非常に高く、リクエストは失敗します（典型的な症状: **出力内で画像が参照されません**）。
**可能であれば、より安定性の高いBase64アップロードを優先してください** — プラットフォームの観点では、これが最も運用に力を入れており、最も信頼性の高い経路です。
URLアップロードは**Geminiネイティブエンドポイント**でのみ動作し、**OpenAI互換モードではURLアップロードはサポートされず**、Base64が必要です。
### Curl の例（fileUri）
```bash theme={null}
curl --location 'https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent' \
--header 'Authorization: Bearer sk-' \
--header 'Content-Type: application/json' \
--data '{
"contents": [
{
"parts": [
{
"fileData": {
"fileUri": "https://raw.githubusercontent.com/apiyi-api/ai-api-code-samples/refs/heads/main/Vision-API-OpenAI/otter.png",
"mimeType": "image/png"
}
},
{
"text": "add five dogs"
}
],
"role": "user"
}
],
"generationConfig": {"responseModalities": ["IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}},
"safetySettings": []
}' > output.json
```
### Pythonの例 (fileUri)
```python theme={null}
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Gemini 3 Pro Image - Image editing (minimal file_uri version)
Purpose: only for a quick check that the endpoint works
"""
import requests
import base64
import json
from pathlib import Path
from datetime import datetime
# ============================================================================
# Configuration
# ============================================================================
API_KEY = "sk-"
API_URL = "https://api.apiyi.com/v1beta/models/gemini-3-pro-image-preview:generateContent"
# Image URL
IMAGE_URL = "https://raw.githubusercontent.com/apiyi-api/ai-pics/refs/heads/main/1762260696217_dd0352c1f9604540.png"
IMAGE_MIME_TYPE = "image/png"
# Edit instructions
EDIT_PROMPT = "Change the person's clothes to a blue jacket and hair to a purple gradient; keep pose, gaze direction, and other structural features unchanged."
SYSTEM_PROMPT = "You are a professional expert in image description and generation. Your task is to produce high-quality image prompts with rich detail and a clear artistic style, or to make accurate, creative edits to existing images, based on the user's request."
# Output parameters
ASPECT_RATIO = "9:16"
RESOLUTION = "4K"
MAX_OUTPUT_TOKENS = 8000
OUTPUT_FILE = f"minimal_{datetime.now().strftime('%Y%m%d_%H%M%S')}.png"
# ============================================================================
# Core
# ============================================================================
def main():
print("=" * 60)
print("Testing file_uri endpoint")
print("=" * 60)
print(f"Image URL: {IMAGE_URL[:80]}...")
print(f"Edit prompt: {EDIT_PROMPT}")
print(f"Output params: {RESOLUTION}, {ASPECT_RATIO}")
print("-" * 60)
# Build the request body
# Note: fileData, mimeType, fileUri must be in camelCase
payload = {
"generationConfig": {
"responseModalities": ["IMAGE", "TEXT"],
"imageConfig": {
"imageSize": RESOLUTION,
"aspectRatio": ASPECT_RATIO
},
"maxOutputTokens": MAX_OUTPUT_TOKENS
},
"contents": [
{
"role": "model",
"parts": [{"text": SYSTEM_PROMPT}]
},
{
"role": "user",
"parts": [
{
"fileData": { # camelCase: fileData (not file_data)
"mimeType": IMAGE_MIME_TYPE, # camelCase: mimeType
"fileUri": IMAGE_URL # camelCase: fileUri
}
},
{"text": EDIT_PROMPT}
]
}
]
}
# Send the request
print("\nSending request...")
try:
response = requests.post(
API_URL,
json=payload,
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}"
},
timeout=300
)
print(f"Response status: {response.status_code}")
if response.status_code != 200:
print(f"❌ Error: {response.text}")
return
# Parse the response
data = response.json()
print("✅ Response received")
# Save full response for debugging
with open(OUTPUT_FILE + ".response.json", "w", encoding="utf-8") as f:
json.dump(data, f, indent=2, ensure_ascii=False)
print(f"📄 Response saved: {OUTPUT_FILE}.response.json")
# Extract and print text
parts = data["candidates"][0]["content"]["parts"]
for part in parts:
if "text" in part:
print(f"\n💬 Text response: {part['text']}")
# Save image
for part in parts:
if "inlineData" in part or "inline_data" in part:
image_data = part.get("inlineData", part.get("inline_data", {})).get("data")
if image_data:
image_bytes = base64.b64decode(image_data)
with open(OUTPUT_FILE, "wb") as f:
f.write(image_bytes)
print(f"\n✅ Image saved: {OUTPUT_FILE}")
print(f"📦 File size: {len(image_bytes) / 1024:.1f} KB")
print(f"🔗 File path: {Path(OUTPUT_FILE).resolve()}")
return
print("⚠️ No image data found in the response")
except requests.Timeout:
print("❌ Request timed out")
except Exception as e:
print(f"❌ Error: {e}")
if __name__ == "__main__":
main()
print("\n" + "=" * 60)
print("Test finished")
print("=" * 60)
```
`fileData`、`mimeType`、および`fileUri`は **camelCase** である必要があります（`file_data` / `file_uri` ではありません）。そうでない場合、パラメータは無視され、画像は参照されません。
## 課金の基本（重要）
* **同期呼び出しの所要時間**: Pro / 2 の 4K では、生成におよそ **30〜150秒** の妥当な時間がかかります
* **タイムアウト時に切断しても課金されます**: たとえば、生成に120秒かかるのにクライアント側のタイムアウトが100秒に設定されていて切断された場合でも、課金は発生します
* **429 / 503 は課金されません**: 失敗したリクエストは課金対象外です（お客様を待たせたり、画像がないまま行き詰まらせたりしないようにしています）
* **コンテンツセーフティによる拒否でも課金されます**: お客様の入力にコンテンツセーフティ上の問題があり、Google が画像生成を拒否した場合でも、**ステータスコード 200 は課金対象** です — エラー処理と下記の保証プランをご覧ください
## タイムアウト設定（重要）
4K画像生成は全体的に時間がかかり、**画像アップロード、API処理、Base64画像ダウンロード** などの段階を含みます（当社のバックエンドでは **API処理時間** に基づいて課金されます）。通常は、4K では約 **50秒** かかります（ポーリングは除く） が、クライアントがタイムアウトを短く設定しすぎると、生成完了前に **早期に切断** され、次のようなエラーが報告されます:
```text theme={null}
API Connection Error: HTTPSConnectionPool(host='api.apiyi.com', port=443): Read timed out. (read timeout=120)
```
より安全にするため、解像度ごとにタイムアウトを設定することをおすすめします:
```python theme={null}
timeout = {
"1K": 300, # 5 minutes - quick preview
"2K": 300, # 5 minutes - recommended
"4K": 600, # 10 minutes - ultra HD
}
```
## マルチターン会話編集（ネイティブは対応、リバースモデルは非対応）
Nano Bananaシリーズは **Gemini ネイティブ形式** を使用し、**真の会話型マルチターン編集** をサポートします。各ターンで生成された画像を `contents` に **`role: "model"` `inlineData`** として戻し、そのうえで次のユーザー指示を送ります。モデルは **会話履歴全体** をもとに編集し、変更を **蓄積** します（例: まずソファの色を変え、その後アクセサリーを追加する — 前の変更は保持されます）。
これは「reverse」画像モデルとは根本的に異なります。組み込む前にここを明確にしておいてください:
| 項目 | Nano Banana (Gemini native) | リバースモデル (例: `gpt-image-2-all`) |
| ------------ | ---------------------------------------------------------------- | ------------------------------------------- |
| エンドポイント | `/v1beta/...:generateContent` | `/v1/chat/completions` (chat-style) |
| マルチターンの仕組み | ✅ **真の会話型**: `role:model` の画像を `contents` にバックフィルし、モデルが履歴を読み取ります | ❌ 会話状態なし: `assistant` の履歴にある画像は **無視** されます |
| ターン間の蓄積 | ✅ 対応（赤いソファ → 帽子を追加してもソファは赤いまま） | ⚠️ 再投入のみ、1ステップ編集 |
| 以前の画像を編集する方法 | 最後の出力を会話履歴内の `model` 画像としてバックフィルする | 以前の画像 URL を参照として **新しいユーザーメッセージ** で渡します |
テスト済み: 以前の画像を `model` ロールのターンとしてバックフィルすると、Nano Banana 2 (`gemini-3.1-flash-image-preview`) は編集を継続して変更を正しく蓄積できます。一方、リバースモデルは **最後のユーザーメッセージ** の参照画像しか読み取らないため、会話履歴を保持してもマルチターンでは機能しません。
最小例（各出力を同じ `contents` にバックフィル）:
```python theme={null}
import requests, base64
API_KEY = "sk-your-api-key"
URL = "https://api.apiyi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
CFG = {"responseModalities": ["IMAGE"], "imageConfig": {"imageSize": "2K"}}
contents = [] # keep one running conversation history
def turn(instruction, save_to):
contents.append({"role": "user", "parts": [{"text": instruction}]})
data = requests.post(URL, headers=H,
json={"contents": contents, "generationConfig": CFG}, timeout=300).json()
part = next(p for p in data["candidates"][0]["content"]["parts"] if "inlineData" in p)
contents.append({"role": "model", "parts": [part]}) # key: backfill the output image
with open(save_to, "wb") as f:
f.write(base64.b64decode(part["inlineData"]["data"]))
turn("Generate an orange cat sitting on a blue sofa, simple line-art style", "step1.png")
turn("Make the sofa red; keep the cat and composition unchanged", "step2.png") # edits the previous image
turn("Put a small yellow hat on the cat; keep everything else the same", "step3.png") # accumulates; red sofa kept
```
詳細（履歴バックフィルと再投入の方式、既存画像からのマルチターン開始）は [画像編集 API · マルチターン会話編集](/ja/api-capabilities/nano-banana-2-image/image-edit#multi-turn-conversational-editing) にあります。
## なぜレスポンスに複数の画像が含まれることがあるのか
`gemini-3-pro-image` を呼び出すと、まれに**1回のレスポンスに複数の image パーツが含まれる**（テストでは 2〜10 枚を確認）ことがあり、ログに散発的に記録される 6000超（5桁に達することもある）の output-token エントリと一致します。これは異常ではありません。Google の公式ドキュメントによると、Gemini 3 の image モデルでは「Thinking」がデフォルトで有効になっており（API では無効化できません）、モデルは構図やロジックを試すために中間画像を生成し、これらの下書きは最終版と並んで `parts` に表示されます。また、「Thinking の中の最後の画像が最終レンダリング画像でもある」とされています（公式ドキュメント: `ai.google.dev/gemini-api/docs/image-generation`）。2026年7月のテスト（Googleネイティブの`generateContent`形式）に基づくと:
| シナリオ | 返される画像数 |
| ----------------------------------------------------- | ------------------------------------- |
| 純粋な text-to-image | 常に 1 枚（prompt で明示的に「複数の画像」を要求しても同じです） |
| 簡単な image 編集（アクセサリー追加 / 背景変更 / スタイル変更） | 常に 1 枚 |
| 複雑なタスク型編集（例: 「4面キャラクターシート + 衣装変更 + 白背景」のように制約が複数あるもの） | 2〜10 枚、安定して再現可能 |
トリガーは**prompt のタスク複雑度**であり、「image editing」そのものではありません。複数の画像は**単一の candidate**内に収まり（複数 candidate ではありません）、各画像は完全な1枚の画像です。これは同じデザインの連続した下書き（同じ構図で、細部だけが少しずつ異なる）であり、**最後のパーツが最終版**です。これらの下書きは通常の image パーツとして返され（`thoughtSignature` フィールドはありますが、`thought: true` フラグはありません）、Google のドキュメントでは Thinking が生成する中間画像は最大 2 枚とされていますが、私たちは複雑なタスクで最大 10 枚まで確認しました。
**課金への影響**: 各画像は固定の token 数で課金されます（1K/2K 解像度では画像1枚あたり 1120 tokens、4K では 2000 tokens）ので、output tokens は画像枚数に対して厳密に線形に増加します。ログ内の 6000超（極端な場合は約 13.5k まで）の output-token エントリは、単に 4〜10 枚の画像レスポンスであり、**課金の異常ではありません**。
**推奨される downstream コード**:
```python theme={null}
parts = response["candidates"][0]["content"]["parts"] or [] # parts is null on safety refusals
images = [p["inlineData"]["data"] for p in parts if "inlineData" in p]
if images:
final_image = images[-1] # last one = final version
```
* **常に parts を反復処理する** — 1レスポンスにつき1枚と決め打ちしないでください。画像ごとのカウントや保存ロジックは、実際のパーツ数に基づいて処理する必要があります
* **1枚だけ必要なときは最後の画像を使う**: 前の下書きは細部が未完成で品質もわずかに低いため、最初の画像を取るのは避けてください
* **prompt で画像枚数を制御するのはほぼ効果がありません**（テストでは、「1枚だけ出力して」の指示は無視されました） — コード側で処理してください
* 複数画像のレスポンスは 35〜142秒（1K 解像度では、画像が増えるほどさらに長くなります）かかり、単一画像よりかなり長いです — 上記のタイムアウト推奨値（5分以上）を維持してください
usageMetadata フィールドの完全な内訳（details と totals の差、拒否レスポンス時のカウントの癖、その他の詳細）については、[Usage Fields と Output の解説](/ja/api-capabilities/nano-banana-usage-metadata) をご覧ください。
## よくある質問
失敗した生成、コンテンツモデレーションポリシー、やさしいプロンプト戦略を診断するための3つの重要指標
失敗した生成のトラブルシューティングとよくある質問
入力に起因しない失敗については、失敗したリクエスト数に応じてクレジットが返還されます
完全なエラーは次のようになります:
```text theme={null}
[&{{write tcp ip:port->ip:port: write: connection reset by peer Unknown error shell_api_error write_response_body_failed} 500 }]
```
これは**たいてい、画像アップロードのサイズ超過が原因です。リクエスト本文が大きくなりすぎて接続が切断されます**。次のベストプラクティスに従ってください:
* **画像枚数を制限する**: 公式ルールの範囲内にしてください（1プロンプトあたり最大14枚 — 上の公式仕様を参照してください）。
* **1枚あたりのサイズを制限する**: 各画像は5MB未満にしてください — 公式の1枚あたり上限は7MBですが、base64エンコードでサイズが約1/3増えるため、余裕を持たせてください。
* **アップロード前にフロントエンドで圧縮する**: APIに送信する前に、フロントエンド（またはサーバー側リレー）で画像を圧縮してください — 一般的には最長辺を制限し、JPEG/WebPに変換し、qualityパラメータを調整します。
* **URL入力に切り替える**: Geminiのネイティブ形式は、`fileData.fileUri` を介して画像URLを渡すことをサポートしており、サイズ超過したbase64リクエスト本文を完全に回避できます — 上の[URL画像入力](#url-image-input)を参照してください。
## ユースケース
* **AIチャットクライアント**: [Cherry Studio](/ja/scenarios/chat/cherry-studio) などのクライアントは、APIYIを介して直接画像を生成するように設定できます
* **生成テスト**: チャットクライアントまたはコンソールでモデルの性能をすばやく確認できます
## 高度な要件
* **画像を URL 経由でアップロードしたいですか?** Gemini のネイティブ エンドポイントは `fileData.fileUri` 経由で画像 URL を渡すことをサポートしています。ただし、OpenAI 互換モードでは URL アップロードに対応していないため、代わりに Base64 を使用してください。上の [URL 画像入力](#url-image-input) のコード例と注意点を参照してください。
* **ダウンロード URL を直接取得したいですか（Base64 の代わりに）?** NB-OSS グループを使用してください — [Nano Banana OSS グループ](/ja/api-capabilities/nano-banana-oss-group) を参照してください。