> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Nano Banana Images API 接続説明 > Nano Banana Image Generation API guide - Ace Data Cloud 本文は Nano Banana Images API の接続と使用について説明します。このインターフェースは二つの機能をサポートしています：**画像生成（generate）** と **画像編集（edit）**。 ## 申請プロセス Nano Banana Images API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API トークンを取得し、保管してください。 ![](https://cdn.acedata.cloud/5hmkdg.jpg) まだログインまたは登録していない場合、自動的にログインページにリダイレクトされ、登録とログインを促されます。完了後、現在のページに自動的に戻ります。 **1つの API トークンでプラットフォームのすべてのサービスを呼び出すことができ、各サービスごとに個別に申請する必要はありません。** 初回申請時には無料のクレジットが付与され、無料で体験できます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で一般残高をチャージできます。 > 📘 完全なドキュメント：[Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images) ## インターフェース概要 * **Base URL**：`https://api.acedata.cloud` * **エンドポイント**：`POST /nano-banana/images` * **認証方式**：HTTP ヘッダーに `authorization: Bearer {token}` を含める * **リクエストヘッダー**： * `accept: application/json` * `content-type: application/json` * **アクション（action）**： * `generate`：テキストプロンプトに基づいて画像を生成 * `edit`：指定された画像に基づいて編集 * **モデル（model）**（オプション）： * `nano-banana`（デフォルト）：Gemini 2.5 Flash Image に基づき、高速で低コスト * `nano-banana-2-lite`：Gemini 3.1 Flash Lite Image に基づき、1K のみサポート、高速生成 * `nano-banana-2`：Gemini 3.1 Flash Image Preview に基づき、Pro レベルの品質 + Flash スピード * `nano-banana-pro`：Gemini 3 Pro Image Preview に基づき、最高品質 * `nano-banana:official`、`nano-banana-2-lite:official`、`nano-banana-2:official`、`nano-banana-pro:official`：対応モデルの公式チャネルバージョン、画質と安定性が向上し、課金が異なる * **非同期コールバック**：オプションで、`callback_url` を通じてタスク完了通知と結果を受信 * **画像数**：オプションで、`count` により 1–4 枚を指定、デフォルトは 1 枚；一部失敗時は成功した画像のみを返却し、課金 ## クイックスタート：画像生成（`action=generate`） **最小必須パラメータ**：`action`、`prompt` プロンプトに基づいて直接画像を生成したい場合、`action` を `generate` に設定し、明確な `prompt` を提供するだけです。 ### リクエスト例（cURL） ```bash theme={null} curl -X POST 'https://api.acedata.cloud/nano-banana/images' \ -H 'authorization: Bearer {token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "action": "generate", "model": "nano-banana-pro", "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を生み出しています。全体の雰囲気は穏やかで熟練しています。縦向きのポートレートオリエンテーション。", "count": 1 }' ``` ### リクエスト例（Python） ```python theme={null} import requests url = "https://api.acedata.cloud/nano-banana/images" headers = { "authorization": "Bearer {token}", "accept": "application/json", "content-type": "application/json", } payload = { "action": "generate", "model": "nano-banana-pro", "prompt": ( "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。" "彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。" "シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。" "85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を生み出しています。" "全体の雰囲気は穏やかで熟練しています。縦向きのポートレートオリエンテーション。" ), "count": 1 } resp = requests.post(url, json=payload, headers=headers) print(resp.json()) ``` ### 成功返却例 ```json theme={null} { "success": true, "task_id": "70e6931b-6e34-43db-9e36-8765e2809d04", "trace_id": "60df8d38-f265-4986-aec7-75c9220bced2", "data": [ { "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を生み出しています。全体の雰囲気は穏やかで熟練しています。縦向きのポートレートオリエンテーション。", "image_url": "https://platform2.cdn.acedata.cloud/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336.png" } ] } ``` ### フィールド説明 * `success`：今回のリクエストが成功したかどうか。 * `task_id`：タスク ID。 * `trace_id`：トレース ID、問題の調査に便利。 * `count`：生成または編集する画像の数、1–4 をサポートし、デフォルトは 1。部分的に失敗した場合、`data` には成功した画像のみが含まれる。 * `data[]`：結果リスト。 * `prompt`：生成に使用されたプロンプト（エコー）。 * `image_url`：生成された画像の直接リンク URL。 > 注：`/nano-banana/images` では `action` と `prompt` のみで画像を生成できます。 ## 画像編集（`action=edit`） 既存の画像に基づいて編集したい場合、`action` を `edit` に設定し、`image_urls` で編集対象の画像リンクリスト（1枚または複数枚）を渡し、同時に編集目標を説明する `prompt` を提供します。 例えば、ここで人物の写真と服の写真を提供し、その人物にその服を着せる場合、画像リンクを同時に渡し、アクションを `edit` に指定します。URL は HTTP URL で、`https` または `http` プロトコルの公開アクセス可能なリンクである必要があります。また、Base64 エンコードされた画像（例：`data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`）も使用できます。 ### リクエスト例（cURL） ```bash theme={null} curl -X POST 'https://api.acedata.cloud/nano-banana/images' \ -H 'authorization: Bearer {token}' \ -H 'accept: application/json' \ -H 'content-type: application/json' \ -d '{ "action": "edit", "prompt": "この男性にこのTシャツを着せてください", "image_urls": [ "https://cdn.acedata.cloud/v8073y.png", "https://cdn.acedata.cloud/44xlah.png" ], "count": 1 }' ``` ### リクエスト例（Python） ```python theme={null} import requests url = "https://api.acedata.cloud/nano-banana/images" headers = { "authorization": "Bearer {token}", "accept": "application/json", "content-type": "application/json", } payload = { "action": "edit", "prompt": "この男性にこのTシャツを着せてください", "image_urls": [ "https://cdn.acedata.cloud/v8073y.png", "https://cdn.acedata.cloud/44xlah.png" ], "count": 1 } resp = requests.post(url, json=payload, headers=headers) print(resp.json()) ``` ### 成功返却例 ```json theme={null} { "success": true, "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3", "trace_id": "a9063166-26ed-4451-85b5-54e896817c69", "data": [ { "prompt": "この男性にこのTシャツを着せてください", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png" } ] } ``` ### フィールド説明 * `image_urls[]`：編集対象の画像URLリスト（公開アクセス可能である必要があります）。複数枚送信可能で、サービスはこれらの素材と`prompt`を組み合わせて編集を行います。 * その他のフィールドは「画像生成」の返却と同様です。 *** ## 非同期コールバック（オプション、推奨） 生成または編集には一定の時間がかかる場合があります。長時間接続を占有しないように、`callback_url`を使用して**Webhookコールバック**を利用することをお勧めします： 1. リクエストボディに`callback_url`を追加します。例えば、あなたのサーバーのWebhookアドレス（公開アクセス可能で、POST JSONをサポートする必要があります）。 2. APIは**即座に**`task_id`を含むレスポンス（または基本的な結果を含む）を返します。 3. タスクが完了すると、プラットフォームは`POST`の方法で完全なJSONを`callback_url`に送信します。あなたは`task_id`を通じてリクエストと結果を関連付けることができます。 **コールバックペイロード例**（フィールド構造は同期成功返却と一致）： ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": [ { "prompt": "白いシャム猫", "image_url": "https://platform.cdn.acedata.cloud/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png" } ] } ``` *** ## エラーハンドリング 呼び出しに失敗した場合、標準エラーフォーマットとトレースIDが返されます。一般的なエラーは以下の通りです： * **400 `token_mismatched`**：リクエストが不正またはパラメータエラー。 * **400 `api_not_implemented`**：インターフェースが実装されていません（サポートに連絡してください）。 * **401 `invalid_token`**：認証失敗またはトークンが欠如。 * **429 `too_many_requests`**：リクエスト頻度が超過。 * **500 `api_error`**：サーバーエラー。 ### エラー応答例 ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "内部サーバーエラーです。" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` *** ## パラメータ対照と注意事項 * **必須**：`action`、`prompt` * **編集専用**：`image_urls`（配列、少なくとも1項目） * **オプション**：`model`（デフォルトは`nano-banana`、選択肢は`nano-banana-2-lite`、`nano-banana-2`、`nano-banana-pro`、または対応する`:official`公式チャネルバージョン）、`aspect_ratio`（アスペクト比、例：`1:1`、`16:9`）、`resolution`（解像度、例：`1K`、`2K`、`4K`；`nano-banana-2-lite`は`1K`のみサポート）、`callback_url`（非同期コールバック用） * **ヘッダー**：`authorization: Bearer {token}`を必ず提供；`accept`は`application/json`に設定することを推奨 * **画像のアクセス性**：`image_urls`は公開アクセス可能な直リンク（HTTP/HTTPS）である必要があり、HTTPSの使用を推奨 * **冪等性とトレース**：`task_id`と`trace_id`を保持し、障害のトラブルシューティングと結果の関連付けを容易にします。