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

TL;DR

它是什么：Google 出品的 Gemini 3 Pro Image，Nano Banana 系列的旗舰档，文生图和参考图编辑共用模型 ID nano-banana-pro。已在 HiAPI 上线，打开模型页输入提示词就能生成，新用户注册送 200 积分，按常规价够出 1 张 2K 图。
多少钱：按张计费，1K 和 2K 同价 $0.057，4K $0.1，按每张输出图计算，比 Google 官方标准价低约 57%–58%，参考图不加价。
API 怎么调：POST https://api.hiapi.ai/v1/tasks，model 写 nano-banana-pro，拿到 taskId 后查询或等回调，下载 data.output[0].url。

Google 的输入 token 费用另计，以上价差比较每张输出图价格。

Nano Banana Pro 能做什么？

2K 不加价。 1K、2K 都是 $0.057 一张，直接出 2K 成片；4K $0.1 一张，留给印刷和大屏。
把字写进画面。 招牌、海报标题、日期这类英文短句直接写进提示词，下面这张金箔招牌的两行字一次写对，没有任何后期。
最多 8 张参考图。 只写提示词是文生图，加上 image_input 就变成编辑或多图融合，同一个模型 ID，代码不用分两套。
10 种画幅加 auto。 1:1、4:5、3:4、9:16、16:9、21:9 等常用比例都有。要 1:4、8:1 这类长条图，或者一次传超过 8 张参考图，选 Nano Banana 2（最多 14 张）。

Nano Banana Pro 原图，未修图，输出 1536×2752。

A hand-painted gold-leaf sign in a modern specialty coffee shop window, elegant serif lettering reading 'MORNING BREW CO.' with a small script subtitle 'est. 2024' beneath it, warm natural daylight streaming through the glass, soft bokeh reflections of a city street, photorealistic commercial photography, crisp perfectly legible typography with correct spelling, shallow depth of field, editorial lighting

用这个提示词生成 →，画幅选 9:16，清晰度选 2K。

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

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

在线试用（约 1 分钟）

打开 Nano Banana Pro 模型页，或者直接点上面招牌图下方的链接，提示词会自动填好。
注册或登录，新账号自带 200 积分。
选画幅和清晰度，常规价 1K、2K 都是 114 积分一张。
点运行，满意就下载。

API 接入（约 5 分钟）

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

2K 一张 $0.057，$10 能出约 175 张。程序员节限时 5 折到北京时间 2026-11-09 00:00，期间 1K、2K 每张 $0.0285，同样 $10 约出 350 张。完整参数见中文文档。

第一张图：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-pro",
    "input": {
      "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
      "aspect_ratio": "16:9",
      "resolution": "2K",
      "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。1K 和 2K 同价，建议每个请求都写上 "resolution": "2K"。

第一张图：Python 版

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

import os
import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}

payload = {
    "model": "nano-banana-pro",
    "input": {
        "prompt": "Minimalist studio product photography, matte-black earbuds case on a warm gradient backdrop, three-point studio lighting",
        "aspect_ratio": "16:9",
        "resolution": "2K",
        "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-pro.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")

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

在 input 里加上 image_input，同一个请求就变成编辑。下面拿一张 Nano Banana Pro 生成的科学馆海报当参考图，只改日期那一行：

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-pro",
    "input": {
      "prompt": "Keep this exact poster: layout, planet, observatory, visitor, colors and headline. Change only the date line to SAT 24 OCT in the same typography and color. No other words.",
      "image_input": ["https://static.hiapi.ai/blog/gpt-image-2-vs-nano-banana-pro/0dba86ff979d-nano-pro-science.png"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

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

上线前注意这 3 件事

服务端用回调。 请求体顶层加 "callback": {"url": "https://yourapp.com/webhook", "when": "final"}，任务结束自动通知，省掉轮询；回调可能重复到达，按 taskId 去重。
超时别重复 POST。 每次 POST /v1/tasks 都会新建任务、单独计费。先存下 taskId，重试前在自己系统里去重。
每个请求显式写 resolution。 默认是 1K，2K 价格相同，定稿时可直接选择 2K；4K 单价更高，只在交付环节用。

常见报错，一行一个

400，提示字段不被允许 → 字段名拼错，或用了别的模型的字段（比如 image_urls）→ 改成 image_input。
400，提示 aspect_ratio 取值不对 → 用了列表外的画幅（如 8:1）→ 从 10 种画幅和 auto 里选一个，长条图换 Nano Banana 2。
401 → Key 缺失、写错或已撤销 → 检查 Authorization: Bearer sk-... 请求头，必要时在控制台重建 Key。
创建成功，任务却是 fail → 查看任务返回的错误；若参考图打不开、格式不受支持，换成公网可访问的 JPEG、PNG 或 WebP 后再提交。
图片链接过期后打不开 → 输出链接带有效期 → 拿到结果后立刻下载，存文件本身。

失败的任务不扣费。

常见问题

Nano Banana Pro 和 Nano Banana 2 怎么选？ 出 2K 两者同价，都是 $0.057 一张。要长条画幅或超过 8 张参考图选 Nano Banana 2；想用 Nano Banana 系列的旗舰档出品牌主视觉，选 Pro。

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

能从 Nano Banana 2 直接切过来吗？ 可以。字段名一样（prompt、image_input、aspect_ratio、resolution、output_format），把 model 改成 nano-banana-pro 即可；画幅只要在 Pro 支持的 10 种之内。

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