跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
申請流程

使用前，請在 XHuoAPI 平台中進入 Nano Banana Images API 並點擊 Acquire 申請開通。首次申請通常會有免費額度可用。開通完成後，即可在平台中獲取到用於調用 API 的 Bearer Token。

​
接口概覽

  • Base URL：https://api.xhuoapi.ai/v1
  • 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：基於 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.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "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.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "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": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "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://platform.cdn.xhuoapi.ai/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。 比如這裡我們提供一張人物照片，一張衣服照片，讓人物穿上這個衣服，就可以同時傳入圖片鏈接，並且指定 action 為 edit，URL 可以是 HTTP URL，以 https 或 http 協議的公開可訪問鏈接，也可以是 Base64 編碼的圖片，如 data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....

​
請求示例（cURL）

curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'

​
請求示例（Python）

import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/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.xhuoapi.ai/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": "a white siamese cat",
      "image_url": "https://platform.cdn.xhuoapi.ai/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：服務端異常。

​
錯誤響應示例

{
  "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 或 nano-banana-pro）、aspect_ratio（寬高比，如 1:1、16:9）、resolution（分辨率，如 1K、2K、4K）、callback_url（用於異步回調）
  • Headers：必須提供 authorization: Bearer {token}；accept 建議設為 application/json
  • 圖片可訪問性：image_urls 必須為可公網訪問的直鏈（HTTP/HTTPS），建議使用 HTTPS
  • 幂等與追蹤：保留 task_id 與 trace_id，便於故障排查與結果關聯