Nano Banana Images API 集成指南

本文将介绍如何集成和使用 Nano Banana Images API。这一接口支持两种功能：图像生成 (generate) 和 图像编辑 (edit)。无论是创建独特的艺术作品，还是对现有图像进行修改，Nano Banana 都能满足您的需求。

环境准备

在使用该 API 之前，请确保您已在 Ace Data Cloud 平台 上申请到 API 的激活权限。首次申请通常会提供免费的配额。激活后，您可以从平台获取用于调用 API 的 Bearer Token。

接口概述

• 基础 URL : https://api.acedata.cloud
• 端点 : POST /nano-banana/images
• 认证方式 : 在 HTTP 头部携带 authorization: Bearer {token}
• 请求头:
• accept: application/json
• content-type: application/json
• 操作:
• generate: 根据文本提示生成图像
• edit: 根据给定的图像进行编辑
• 模型 (可选):
• nano-banana (默认): 基于 Gemini 2.5 Flash Image，快速、低成本
• nano-banana-2: 基于 Gemini 3.1 Flash Image Preview，专业级质量 + 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": "A photorealistic close-up portrait of an elderly Japanese ceramicist...",
    "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": (
        "A photorealistic close-up portrait of an elderly Japanese ceramicist..."
    ),
    "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...",
      "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。

注意：生成图像时，仅需提供 action 和 prompt。

编辑图像 (action=edit)

如果您想基于现有图像进行编辑，请将 action 设置为 edit，并通过 image_urls 传递待编辑的图像 URL（至少 1 个），同时提供描述编辑目标的 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": "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 回调：

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.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": "Internal server error."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

总结

通过 Nano Banana Images API，您可以轻松生成和编辑图像，提升您的应用程序或项目的视觉表现。无论您是艺术创作者还是应用开发者，这一工具都能为您提供强大的支持。希望本文能帮助您顺利集成和使用该 API。

技术标签

• API集成
• 图像处理