Nano Banana Images API 串接說明

本文介紹 Nano Banana Images API 的串接與使用。此介面支援兩種能力：圖像生成（generate） 與 圖像編輯（edit）。

申請流程

要使用 Nano Banana Images API，首先前往 Ace Data Cloud 控制台取得您的 API Token，留作備用。

如果您尚未登入或註冊，會自動跳轉至登入頁面邀請您註冊和登入，完成後會自動返回目前頁面。 一個 API Token 即可呼叫平台所有服務，無需為每個服務個別申請。 首次申請會贈送免費額度，可免費體驗；額度不足時可於控制台儲值通用餘額。

📘 完整文件：Nano Banana Images API →

介面概覽

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-2.1：新一代高效率圖像模型，支援 1K、2K、4K 生圖與編輯
- 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）

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）

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

成功回傳範例

{
  "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。例如這裡我們提供一張人物照片與一張衣服照片，讓人物穿上這件衣服，即可同時傳入圖片連結，並指定 action 為 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": "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）

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": "let this man wear on this T-shirt",
    "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": "let this man wear on this T-shirt",
      "image_url": "https://platform.cdn.acedata.cloud/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}

欄位說明

image_urls[]：待編輯圖片 URL 清單（必須可從公網存取）。可傳送多張，服務會結合這些素材與 prompt 完成編輯。
其餘欄位同「生成圖片」回傳。

非同步回呼（可選，建議）

生成或編輯可能需要一定時間。為避免長連線佔用資源，建議透過 callback_url 使用 Webhook 回呼：

在請求主體中新增 callback_url，例如你的伺服器 Webhook 位址（需可從公網存取，支援 POST JSON）。
API 會 立即回傳 包含 task_id 的回應（或包含基本結果）。
當任務完成後，平台將以 POST 的方式將完整 JSON 傳送至 callback_url。你可以透過 task_id 將請求與結果關聯。

回呼承載資料範例（欄位結構與同步成功回傳一致）：

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "a white siamese cat",
      "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：伺服器異常。

錯誤回應範例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

參數對照與注意事項

必填：action、prompt
編輯專用：image_urls（陣列，至少 1 項）
可選：model（預設 nano-banana，可選 nano-banana-2-lite、nano-banana-2、nano-banana-2.1、nano-banana-pro；除 nano-banana-2.1 外還有對應的 :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，以利故障排查與結果關聯

入門

AI 聊天

AI 圖像

AI 視頻

AI 音頻

網絡與數據

驗證碼

身份

Coding

更多指南

Nano Banana Images API 串接說明

申請流程

介面概覽

快速開始：生成圖片（`action=generate`）

請求範例（cURL）

請求範例（Python）

成功回傳範例

欄位說明

編輯圖片（`action=edit`）

請求範例（cURL）

請求範例（Python）

成功回傳範例

欄位說明

非同步回呼（可選，建議）

錯誤處理

錯誤回應範例

參數對照與注意事項

​申請流程

​介面概覽

​快速開始：生成圖片（action=generate）

​請求範例（cURL）

​請求範例（Python）

​成功回傳範例

​欄位說明

​編輯圖片（action=edit）

​請求範例（cURL）

​請求範例（Python）

​成功回傳範例

​欄位說明

​非同步回呼（可選，建議）

​錯誤處理

​錯誤回應範例

​參數對照與注意事項

申請流程

介面概覽

快速開始：生成圖片（`action=generate`）

請求範例（cURL）

請求範例（Python）

成功回傳範例

欄位說明

編輯圖片（`action=edit`）

請求範例（cURL）

請求範例（Python）

成功回傳範例

欄位說明

非同步回呼（可選，建議）

錯誤處理

錯誤回應範例

參數對照與注意事項