メインコンテンツへスキップ
本文は Nano Banana Images API の接続と使用について説明します。このインターフェースは二つの機能をサポートしています：画像生成（generate） と 画像編集（edit）。

​
申請プロセス

使用する前に、Ace Data Cloud プラットフォームで Nano Banana Images API にアクセスし、Acquire をクリックして開通を申請してください。初回申請では通常、無料の利用枠が利用可能です。開通が完了したら、プラットフォームで API を呼び出すための Bearer Token を取得できます。

​
インターフェース概要

  • 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：Gemini 3.1 Flash Image Preview に基づき、Pro レベルの品質 + Flash スピード
    • nano-banana-pro：Gemini 3 Pro Image Preview に基づき、最高品質
  • 非同期コールバック：オプションで、callback_url を通じてタスク完了通知と結果を受信

​
クイックスタート：画像生成（action=generate）

最小必須パラメータ：action、prompt プロンプトに基づいて直接画像を生成したい場合は、action を generate に設定し、明確な prompt を提供してください。

​
リクエスト例（cURL）

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",
    "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。",
    "count": 1
  }'

​
リクエスト例（Python）

import requests

url = "https://api.acedata.cloud/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": (
        "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。"
        "彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。"
        "シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。"
        "85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。"
        "全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。"
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())

​
成功返却例

{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "深い日焼けのしわと温かく知恵のある微笑を持つ高齢の日本の陶芸家のフォトリアリスティックなクローズアップポートレート。彼は新しく釉薬をかけた茶碗を注意深く検査しています。設定は彼の素朴で日差しの差し込む作業場です。シーンは窓から差し込む柔らかいゴールデンアワーの光に照らされ、粘土の細かい質感を強調しています。85mm ポートレートレンズで撮影され、柔らかくぼやけた背景（ボケ）を実現しています。全体の雰囲気は穏やかで熟練しています。縦型ポートレートの向き。",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}

​
フィールド説明

  • success：今回のリクエストが成功したかどうか。
  • task_id：タスク ID。
  • trace_id：トレース ID、問題の調査に役立ちます。
  • 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）

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）

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())

​
成功返却例

{
  "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を使用してリクエストと結果を関連付けることができます。
コールバックペイロードの例（フィールド構造は同期成功の返却と一致）： 
{
  "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：サーバーエラー。

​
エラーレスポンスの例

{
  "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またはnano-banana-proも選択可能）、aspect_ratio（アスペクト比、例：1:1、16:9）、resolution（解像度、例：1K、2K、4K）、callback_url（非同期コールバック用）
  • ヘッダー：authorization: Bearer {token}を必ず提供；acceptはapplication/jsonに設定することを推奨
  • 画像の可アクセス性：image_urlsは公開アクセス可能な直リンク（HTTP/HTTPS）でなければならず、HTTPSの使用を推奨
  • 冪等性とトレース：task_idとtrace_idを保持し、障害調査と結果の関連付けを容易にすること