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

TL;DR

它是什么：Google 出品、Nano Banana 系列的最新版本，文生图和参考图编辑共用一个模型 ID。已在 HiAPI 上线，打开模型页输入提示词就能生成，新用户注册送 200 积分，够出约 4 张 1K 图。
多少钱：按张计费，1K $0.022、2K $0.036、4K $0.058，比 Nano Banana 2 低约 33%–39%，参考图不加价。
API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 gemini-nano-banana-2.1，拿到 taskId 后查询或等回调，下载 data.output[0].url。

刚上线的 Nano Banana 2.1，最多人问两件事：能做什么，多久能接进自己的项目。前者看下面 5 点，后者 5 分钟就够。

Nano Banana 2.1 能做什么？

比 NB 2 便宜三到四成。 同分辨率每张便宜约 33%–39%，1K 只要 $0.022，参数写法和 NB 2 一样。
一次喂 10 张参考图。 模特、服装、场景、产品图一起传进去，融合成一张，适合换装和品牌视觉提案。
15 种画幅，最长到 1:8 和 8:1。 除了常见的 1:1、4:5、16:9、21:9，还能出 1:4、4:1、1:8、8:1 这样的长条图，详情页长图和横幅一次成型。
1K、2K、4K 三档分辨率。 1K 用来试提示词，2K、4K 用来出成片。
文生图和编辑是同一个模型 ID。 只给提示词就是文生图，加上参考图就变成编辑，代码不用分两套。

Nano Banana 2.1 时装大片，2K / 16:9，输出 2752×1536。

用这个提示词生成 →

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

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

在线试用（约 1 分钟）

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

API 接入（约 5 分钟）

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

1K 一张 $0.022，$10 能出约 450 张，足够把提示词调到满意。完整参数见中文文档。

第一张图：curl 版

创建任务：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
      "aspect_ratio": "4:5",
      "resolution": "2K",
      "output_format": "png"
    }
  }'

返回的任务 ID 在 data.taskId：

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

查询结果：

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

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

第一张图：Python 版

创建、轮询、下载一次写完，复制后换上自己的 Key 就能跑：

import requests, time

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "gemini-nano-banana-2.1",
    "input": {
        "prompt": "A fashion editorial photograph of a model in an ivory linen blazer on a sunlit white-stucco terrace above the Mediterranean, 50mm lens, soft directional light, cinematic color grade",
        "aspect_ratio": "4:5",
        "resolution": "2K",
        "output_format": "png",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]

while True:
    status = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if status["status"] in ("success", "fail"):
        break
    time.sleep(2)

if status["status"] == "success":
    image_url = status["output"][0]["url"]
    with open("nano-banana-2-1.png", "wb") as f:
        f.write(requests.get(image_url, timeout=60).content)
else:
    print(status.get("error"))

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

在 input 里加上 image_input，同一个请求就变成编辑。下面直接拿上面那张时装大片当参考图，只换外套颜色：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "input": {
      "prompt": "Change the model'\''s blazer to deep burgundy silk while keeping her pose, the terrace, and the lighting unchanged",
      "image_input": ["https://static.hiapi.ai/model-examples/gemini-nano-banana-2.1/2026/10/08/1791466473082-3e77d5c2a1ef0ef6-coastal-fashion-2k.webp"],
      "resolution": "2K"
    }
  }'

image_input 最多放 10 个公网 URL，支持 JPEG、PNG、WebP，单张不超过 30MB。提示词里把"改什么"和"保留什么"分开写，保留项越具体，原图越稳。

上线前注意这 3 件事

服务端用回调。 请求体里加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务结束自动通知，省掉轮询。
超时别重复 POST。 每次 POST /v1/tasks 都会新建任务、单独计费。先存下 taskId，重试前在自己系统里去重。
每个请求显式写 resolution。 分辨率直接决定单价，写死在请求里，账单才可预期。

常见报错，一行一个

400 additional properties '<field>' not allowed → 字段名拼错，或用了别的模型的字段（比如 image_urls）→ 对照文档改成 image_input 等正确字段名。
400，提示 aspect_ratio 取值不对 → 传了不在列表里的画幅 → 从报错里列出的 15 个合法值中选一个。
401 permission_denied → Key 缺失、写错或已撤销 → 检查 Authorization: Bearer sk-... 请求头，必要时在控制台重建 Key。
创建成功，任务却是 fail / INVALID_REQUEST → 参考图 URL 打不开或不是图片 → 换成公网可直接访问的 JPEG、PNG 或 WebP。
图片链接过几天打不开 → 输出链接带有效期 → 拿到结果后立刻下载，存文件本身。

失败的任务预扣金额会自动全额退还。

常见问题

Nano Banana 2.1 能直接替换 NB 2 吗？ 可以。参数名完全一样，把 model 改成 gemini-nano-banana-2.1 就能切换，同分辨率每张便宜约 33%–39%。唯一要注意：2.1 默认输出 JPG，需要 PNG 就显式写 "output_format": "png"。

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

能出透明背景吗？ 输出格式是 jpg 或 png，要透明背景的素材选 GPT Image 2.5，它在 1K 支持 background: transparent。

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