> ## 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 整合指南 - Ace Data Cloud

本文介紹 Nano Banana Images API 的對接與使用。該接口支持兩種能力：**圖像生成（generate）** 與 **圖像編輯（edit）**。

## 申請流程

要使用 Nano Banana Images API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 獲取您的 API Token，留作備用。

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

如果你尚未登錄或註冊，會自動跳轉到登錄頁面邀請你註冊和登錄，完成後會自動返回當前頁面。

**一個 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://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`。

比如這裡我們提供一張人物照片，一張衣服照片，讓人物穿上這個衣服，就可以同時傳入圖片鏈接，並且指定 action 為 `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": "let this man wear on this T-shirt",
    "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。
* **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`，便於故障排查與結果關聯