教程
如何使用 Nano Banana 2 Lite API：curl、Python 与一个可运行的请求
Nano-Banana-2-Lite 是 hiapi 上 Nano-Banana 图像模型家族中的经济款：与它的更大兄弟模型采用相同的基于任务的 workflow，单张图像价格更低，并且同时支持文生图和参考图编辑。本指南将带你走完一条完整、可运行的集成流程——创建任务、轮询任务、下载结果——分别用 curl 和 Python 演示，并说明它与 Nano-Banana-2 和 Nano-Banana-Pro 不同的 schema 细节。
你将构建什么，以及需要准备什么
目标：向 Nano-Banana-2-Lite 发送一个 prompt，等待图像生成，并将其保存到磁盘。
你只需要一样东西：一个 hiapi API key（sk-...）。从你的 hiapi dashboard 获取。单张图像的费用列在 pricing page 和 Nano Banana 2 Lite 模型页面 上。
hiapi 上的所有图像模型都通过统一的 async task API 运行：你 POST /v1/tasks 创建任务，然后要么轮询 GET /v1/tasks/{id}，要么在任务完成时接收 webhook。
最小可运行请求（curl）
创建任务：
curl -s -X POST https://api.hiapi.ai/v1/tasks \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Nano-Banana-2-Lite",
"input": {
"prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
"aspect_ratio": "3:2"
}
}'
响应中包含的任务 id 位于 data.taskId。轮询它：
curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
-H "Authorization: Bearer sk-YOUR_KEY"
当 data.status 为 "success" 时，图像 URL 位于 data.output[0].url。请立即下载——输出 URL 带有签名并带有过期时间（expireAt），所以要保存字节，而不是链接。
两条容易让人踩坑的 schema 规则，直接来自 API 自身的校验：
- 模型 id 区分大小写。
"model": "nano-banana-2-lite"会返回400 MODEL_UNAVAILABLE（"model not available via /v1/tasks"）。请使用精确的 idNano-Banana-2-Lite。 prompt和aspect_ratio都是必填项。 省略其中任何一个都会收到400 INVALID_REQUEST以及missing required field消息。有效的aspect_ratio值：auto、1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9、1:4、4:1、1:8、8:1。
Python 中的相同流程
无需 SDK——任务 API 就是基于 HTTPS 的纯 JSON：
import os
import time
import requests
API_BASE = "https://api.hiapi.ai/v1"
HEADERS = {
"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
"Content-Type": "application/json",
}
# 1. Create the task
resp = requests.post(
f"{API_BASE}/tasks",
headers=HEADERS,
json={
"model": "Nano-Banana-2-Lite",
"input": {
"prompt": "A watercolor illustration of a lighthouse at dawn, soft pastel palette",
"aspect_ratio": "3:2",
},
},
timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task created:", task_id)
# 2. Poll until the task reaches a terminal state
deadline = time.time() + 600
while time.time() < deadline:
task = requests.get(
f"{API_BASE}/tasks/{task_id}", headers=HEADERS, timeout=30
).json()["data"]
if task["status"] == "success":
break
if task["status"] == "fail":
err = task.get("error") or {}
raise RuntimeError(f"task failed: {err.get('code')}: {err.get('message')}")
time.sleep(3)
else:
raise TimeoutError(f"task {task_id} did not finish in 10 minutes")
# 3. Download immediately — output URLs are signed and expire
image_url = task["output"][0]["url"]
with open("lighthouse.png", "wb") as f:
f.write(requests.get(image_url, timeout=120).content)
print("saved lighthouse.png")
用参考图编辑：是 image_urls，不是 image_input
Nano-Banana-2-Lite 支持图像编辑，但它的参考图字段是 image_urls——一个最多包含 10 个可公开访问 URL 的数组：
{
"model": "Nano-Banana-2-Lite",
"input": {
"prompt": "Replace the background with a clean white studio backdrop, keep the product unchanged",
"aspect_ratio": "auto",
"image_urls": ["https://your-cdn.com/product-photo.jpg"]
}
}
这是该家族最容易踩的坑：Nano-Banana-2 和 Nano-Banana-Pro 使用 image_input 实现同样目的，而 Lite 会拒绝该字段（additional properties 'image_input' not allowed）。像 input_urls、images 或 reference_images 这样的字段名在三个模型上都会被拒绝。如果你在层之间迁移代码，通常唯一需要的改动就是这一个字段改名。
Lite vs. Nano-Banana-2 vs. Pro：重要的 schema 差异
| Nano-Banana-2-Lite | Nano-Banana-2 | Nano-Banana-Pro | |
|---|---|---|---|
| 必填输入 | prompt、aspect_ratio |
prompt |
prompt |
| 参考图 | image_urls（≤10） |
image_input |
image_input |
resolution 控制 |
不接受 | 接受 | 接受 |
Lite 保持接口面极简：prompt、宽高比、可选参考图。没有 resolution、seed、n 或 negative_prompt——发送其中任何一个都会因 additional properties ... not allowed 校验失败。如果你需要显式分辨率控制（1K/2K/4K）或更高保真的层级，请升级到 Nano-Banana-2 或 Nano-Banana-Pro；如果你在批量生成——缩略图、草稿、迭代循环、批量变体——Lite 更低的单张图像成本正是它的意义所在。
生产环境加固
尽可能使用 webhook 而非轮询。 在创建任务时添加一个 callback 块，hiapi 会将最终结果 POST 到你的 endpoint：
{
"model": "Nano-Banana-2-Lite",
"input": { "prompt": "...", "aspect_ratio": "1:1" },
"callback": { "url": "https://your-app.com/webhooks/hiapi", "when": "final" }
}
when 只接受 "final"——无论成功或失败，你都只会收到一次 callback。轮询适合脚本和 notebook；callbacks 更适合服务器，因为它们让你不必管理轮询循环和超时。如果你确实要轮询，2–5 秒的间隔加上硬性截止时间（如 Python 示例中那样）就足够了。
处理两层错误。 请求级失败会以 HTTP 错误返回——无效或未授权的 key 会返回 401 以及 {"error": {"code": "permission_denied", "type": "hiapi_error", ...}}，schema 错误会返回 400 INVALID_REQUEST 以及精确的校验消息。任务级失败会以 status: "fail" 和任务自身上的 error 对象到达；在你的代码中要处理这两条路径。
让重试具备幂等性。 任务创建不是幂等的——重试一个超时的创建请求可能会产生两个任务（以及两次计费）。在收到 taskId 后立即持久化它，重启后继续轮询已有 id，而不是盲目重新创建。
存储字节，而不是 URL。 输出 URL 会过期。在对图像做任何其他事情之前，先下载图像并放入你自己的存储。
相关阅读
- Nano Banana 2 Lite 模型页面 — 参数、实时价格、playground
- GPT Image 2 vs Nano Banana 2：使用相同 prompt 的并排对比
- 在 hiapi 上用 Nano-Banana 保持角色一致性
- hiapi 文档 和 定价
FAQ
为什么我收到 "model not available via /v1/tasks"？
模型 id 区分大小写。请精确使用 Nano-Banana-2-Lite；小写变体会被拒绝并返回 400 MODEL_UNAVAILABLE。
Nano-Banana-2-Lite 支持图生图编辑吗？
支持。将参考图传入 image_urls 数组（最多 10 个 URL）。它可以处理背景替换、风格迁移，以及由 prompt 驱动的按指令编辑工作流。
为什么我的 Nano-Banana-2 代码在 Lite 上失败并报 "additional properties 'image_input' not allowed"？
不同层使用不同的参考图字段名：Lite 期望 image_urls，而 Nano-Banana-2 和 Pro 期望 image_input。切换层时请重命名字段。
我可以设置 resolution、seed 或图像数量吗？
Lite 上不行——它的输入 schema 只接受 prompt、aspect_ratio 和 image_urls。要获得 1K/2K/4K 的 resolution 控制，请使用 Nano-Banana-2 或 Nano-Banana-Pro。
输出图像 URL 的有效期是多久？
它们是带有过期时间戳的签名 URL（输出对象中的 expireAt）。请立即下载字节并存储到你自己的存储中；永远不要对任务输出进行热链接。
401 permission_denied 是什么意思？
你的 API key 无效，或者它不允许使用此模型。请在你的 dashboard 中检查 key，并确保以 Authorization: Bearer sk-... 形式发送。
Nano-Banana-2-Lite 每张图像多少钱？ 按用量计费，按图像计费，定位为 Nano-Banana 家族中成本最低的层级。当前费率见 pricing page。
