> ## 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 の連携と使用方法を紹介します。このインターフェースは 2 つの機能をサポートしています：**画像生成（generate）** と **画像編集（edit）**。

## 申請フロー

Nano Banana Images API を使用するには、まず [Ace Data Cloud コンソール](https://platform.acedata.cloud/console/applications) で API Token を取得し、控えておいてください。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

まだログインまたは登録していない場合は、ログインページに自動的にリダイレクトされ、登録とログインを促されます。完了後、自動的に現在のページへ戻ります。

**1 つの API Token でプラットフォームのすべてのサービスを呼び出せるため、サービスごとに個別申請する必要はありません。** 初回申請時には無料クレジットが付与され、無料でお試しいただけます。クレジットが不足した場合は、[コンソール](https://platform.acedata.cloud/console/coin) で共通残高をチャージできます。

> 📘 完全なドキュメント：[Nano Banana Images API →](https://platform.acedata.cloud/documents/nano-banana-images)

## インターフェース概要

* **Base URL**：`https://api.acedata.cloud`
* **Endpoint**：`POST /nano-banana/images`
* **認証方式**：HTTP Header に `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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist "
        "with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully "
        "inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched "
        "workshop. The scene is illuminated by soft, golden hour light streaming through "
        "a window, highlighting the fine texture of the clay. Captured with an 85mm "
        "portrait lens, resulting in a soft, blurred background (bokeh). The overall mood "
        "is serene and masterful. Vertical portrait orientation."
    ),
    "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": "A photorealistic close-up portrait of an elderly Japanese ceramicist with deep, sun-etched wrinkles and a warm, knowing smile. He is carefully inspecting a freshly glazed tea bowl. The setting is his rustic, sun-drenched workshop. The scene is illuminated by soft, golden hour light streaming through a window, highlighting the fine texture of the clay. Captured with an 85mm portrait lens, resulting in a soft, blurred background (bokeh). The overall mood is serene and masterful. Vertical portrait orientation.",
      "image_url": "https://cdn.acedata.cloud/assets/examples/nanobanana/1d0160b4-93f9-4229-8926-ea9ef0bed336-34b3dc2195e8.png"
    }
  ]
}
```

### フィールド説明

* `success`：今回のリクエストが成功したかどうか。
* `task_id`：タスク ID。
* `trace_id`：トレーシング ID。問題の調査に便利です。
* `count`：リクエストする生成または編集画像の数。1～4 をサポートし、デフォルトは 1 です。`data` には生成に成功した画像のみが含まれ、実際に返された枚数に応じて課金されます。各生成呼び出しでは、プロバイダーのネイティブ安全ポリシーが強制的に適用されます。ある呼び出しが拒否されても、他の成功した呼び出しには影響しません。すべての呼び出しが拒否された場合は 403 が返されます。
* `data[]`：結果リスト。
  * `prompt`：生成に使用したプロンプト（エコー）。
  * `image_url`：生成画像への直接 URL。

> 注：`/nano-banana/images` は `action` と `prompt` のみで画像を生成できます

## 画像編集（`action=edit`）

既存の画像に基づいて編集したい場合は、`action` を `edit` に設定し、`image_urls` を通じて編集対象の画像リンクリスト（1 枚または複数枚）を渡すとともに、編集の目的を説明する `prompt` を指定します。

たとえば、人物写真と服の写真を 1 枚ずつ用意し、その人物にその服を着せたい場合、画像リンクを同時に渡し、action を `edit` に指定できます。URL は、`https` または `http` プロトコルの公開アクセス可能な HTTP URL、あるいは `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....` のような Base64 エンコード画像を使用できます。

### リクエスト例（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`**：認証に失敗したか、Token が不足しています。
* **403 `forbidden`**：プロバイダーのネイティブセキュリティポリシーにより、リクエストまたは生成結果が拒否されました。この呼び出しでは画像は返されず、課金もされません。複数画像のリクエストでは、他の成功した呼び出しについては返却および課金される場合があります。
* **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`（非同期コールバック用）
* **Headers**：`authorization: Bearer {token}` を必ず提供する必要があります。`accept` は `application/json` に設定することを推奨します。
* **画像のアクセス可能性**：`image_urls` はパブリックネットワークからアクセス可能な直リンク（HTTP/HTTPS）である必要があります。HTTPS の使用を推奨します。
* **冪等性と追跡**：障害調査と結果の関連付けを容易にするため、`task_id` と `trace_id` を保持してください。


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