Nano Banana 2 API 怎么用？5 分钟跑通第一张图

TL;DR

• 它是什么：Google 出品的 Nano Banana 2，文生图和参考图编辑共用一个模型 ID nano-banana-2，一次最多传 14 张参考图。已在 HiAPI 上线，打开模型页 输入提示词就能生成，新用户注册送 200 积分。
• 多少钱：按张计费，1K $0.036、2K $0.057、4K $0.086，参考图不加价，失败自动退款。
• API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 nano-banana-2，拿到 taskId 后查询或等回调，下载 data.output[0].url。

Nano Banana 2 能做什么？

• 一个模型两种用法。 只给提示词就是文生图，加上 image_input 就变成参考图编辑，不用切换接口或模式。
• 一次最多 14 张参考图。 产品多角度图、模特图、场景图一起传进去，适合做同款换场景、换装和品牌套图。
• 14 种固定画幅加 auto。 常见的 1:1、4:5、16:9、21:9 之外，还有 1:4、4:1、1:8、8:1；不确定时用默认的 auto。
• 1K、2K、4K 三档。 1K 用来试提示词，2K、4K 出成片；默认输出 PNG。

下面这张是 Nano Banana 2 模型页的示例图，4:3、1K 出图：

A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography, 4:3

用这个提示词生成 →

两条上手路线：在线试用还是 API？

先看效果选在线试用，要接进产品选 API。两条路是同一个模型、同一套价格。

在线试用（约 1 分钟）

1. 打开 Nano Banana 2 模型页，或直接点上图下方的链接，提示词会自动填好。
2. 注册或登录，新账号自带 200 积分。
3. 选画幅和分辨率，常规价 1K 一张 72 积分。
4. 点生成，满意就下载。

API 接入（约 5 分钟）

1. 在 HiAPI 控制台 创建 API Key（sk-...）。
2. POST /v1/tasks 创建任务，响应里拿到 data.taskId。
3. 用 GET /v1/tasks/{id} 查询，或在请求体里带上 callback.url 等通知。
4. data.status 变成 success 后，从 data.output[0].url 下载图片。

1K 一张 $0.036，$10 能出约 277 张，足够把提示词调顺。完整参数见 中文文档。

第一张图：curl 版

创建任务：

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
      "aspect_ratio": "4:3",
      "resolution": "1K",
      "output_format": "png"
    }
  }'

返回的任务 ID 在 data.taskId：

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

查询结果：

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

必填的只有 prompt。aspect_ratio 默认 auto，resolution 默认 1K，output_format 默认 png（可选 jpg）。

第一张图：Python 版

先安装 requests（python3 -m pip install requests），并在终端设置 HIAPI_API_KEY（export HIAPI_API_KEY="sk-YOUR_KEY"）。下例创建任务、最多轮询 10 分钟，再下载图片；超时后保留 taskId 继续查询：

import os
import time
import uuid
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
HEADERS["Idempotency-Key"] = str(uuid.uuid4())  # Save with this business task before submitting.

payload = {
    "model": "nano-banana-2",
    "input": {
        "prompt": "A mystical tropical rainforest at night with hundreds of glowing fireflies, warm golden lights floating among dark green ferns and moss, soft mist, dreamy bokeh, cinematic fantasy photography",
        "aspect_ratio": "4:3",
        "resolution": "1K",
        "output_format": "png",
    },
}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


task_id = task_data(requests.post(API, headers=HEADERS, json=payload, timeout=30))["taskId"]
print(f"taskId: {task_id}", flush=True)  # Save this ID for later queries.

deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    task = task_data(requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30))
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        image = requests.get(image_url, timeout=60)
        image.raise_for_status()
        with open("nano-banana-2.png", "wb") as f:
            f.write(image.content)
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task {task_id} failed: {task}")
    time.sleep(3)
else:
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")

参考图编辑：加一个 image_input 就够了

在 input 里加上 image_input，同一个请求就变成编辑。下面把一张白底精华瓶产品图放到浴室台面上：

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "input": {
      "prompt": "Place this exact serum bottle, unchanged, on a white marble bathroom counter next to a folded beige linen towel, soft warm morning window light",
      "image_input": ["https://static.hiapi.ai/blog/nano-banana-ecommerce-product-images-hiapi/shot-1-listing.jpg"],
      "aspect_ratio": "4:3",
      "resolution": "1K"
    }
  }'

image_input 是 URL 数组，最多 14 张，必须是公网能直接打开的图片链接，不支持 SVG。提示词里写清"保留什么"（this exact serum bottle, unchanged），产品标签和瓶型就更稳。这组同款换场景的完整提示词和成图，在 Nano Banana 2 提示词大全 里。

上线前注意这 3 件事

1. 服务端用回调。 请求体顶层加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务结束自动通知；成功和失败都会回调，按 taskId 去重。
2. 重试带上幂等键。 每次 POST /v1/tasks 默认都会新建任务、单独计费。请求头加 Idempotency-Key，为同一业务任务生成并保存一个键，网络超时后用同一账户、同一个键和完全相同的请求体重试，只会创建一次任务。
3. 拿到结果先下载。 输出链接有有效期，先把图片存到自己的存储，再做后续处理。

常见报错，一行一个

• 400 additional properties ... not allowed → 字段名拼错，或用了别的模型的字段（比如 Nano Banana 2 Lite 的 image_urls、写成 size）→ 改成 image_input、resolution。
• 400，aspect_ratio 取值不对 → 传了列表外的画幅 → 从 15 个合法值里选一个。
• 401 permission_denied → Key 缺失、写错或已撤销 → 检查 Authorization: Bearer sk-... 请求头，必要时在控制台重建。
• 402 → 余额不足，任务没有创建，也不扣费 → 充值后重试。
• 任务 status 为 fail → 按返回的 error 改请求，别原样重试；预扣金额会自动全额退还。

常见问题

模型 ID 怎么写？ 写 nano-banana-2。参数名和 Nano Banana 2.1 完全一样，换成 gemini-nano-banana-2.1 就能切到 2.1。

参考图会额外收费吗？ 不会。价格只看输出分辨率，传 1 张还是 14 张参考图都一样。

一次能出几张？ 一个任务出一张。要多张就并发创建多个任务，按张计费。

限时活动价怎么拿？ 不用改代码。程序员节 5 折到北京时间 2026-11-09 00:00，API 和在线试用自动按 5 折计费，1K 一张 $0.018。

Nano Banana 2 系列文章

• Nano Banana 2 模型页：在线生成，注册送 200 积分
• Nano Banana 2 API 多少钱：1K/2K/4K 单价和月度预算
• GPT Image 2.5 vs Nano Banana 2：同提示词 9 张图对照
• Nano Banana 2 提示词大全：5 个场景直接复制出图
• Nano Banana 2.1 API 价格：比 NB 2 便宜多少
• Nano Banana Pro API 价格：每张多少钱
• Nano Banana 2 中文接入文档：全部参数

现在就试：点上面雨林图下方的 用这个提示词生成 →，提示词已经填好，比例选 4:3、清晰度选 1K，运行后下载结果，常规价每张 $0.036。