如何通过 HiAPI API 使用 Nano-Banana-2-Lite：curl、Python 与一个可用的请求

Nano-Banana-2-Lite 是什么，以及何时使用它

Nano-Banana-2-Lite 是 HiAPI 上 Nano-Banana 家族中的超低成本档位。它面向高并发、对成本敏感的图片生成场景，在这些场景中你更看重可预测的开销和快速迭代，而非最高保真度。如果你正在为一个功能做原型、批量生成缩略图或变体，或者运行可以容忍更轻量模型的后台任务，这个档位就是合适的起点。

当输出只是更大流水线中的一环时使用它：草稿视觉、占位图、批量实验，或需要以低成本获得大量候选的 A/B 测试。对于最终的主视觉素材，或需要最高细节的场景，请升级到更大的档位。API 接口保持不变，因此你无需重写集成即可切换模型。

前置条件与请求结构

在调用 Nano-Banana-2-Lite 之前，请确保你已具备：

• 一个 HiAPI 账户和一个 API 密钥。将其保存在环境变量中，例如 HIAPI_API_KEY；切勿将其提交到源代码管理中。
• 一个带 curl 的终端用于首次测试，以及 Python 3.8+ 和 requests 库用于脚本版本。
• 一个描述你想要的图片的提示词。从简单开始；之后可以添加参考输入。

对 HiAPI 的每个请求都遵循相同结构：向模型端点发送一个带 JSON 体的 POST。请求体携带模型名称、提示词以及任何可选参数。由于生成是异步的，提交调用会返回一个任务标识符，然后你轮询该任务。响应是 JSON，错误包含状态码和一条你可以记录的消息。

你的载荷至少需要将 model 设为 nano-banana-2-lite，并提供一个 prompt。可选字段如 reference_images 和输出设置将在后续章节中介绍。

一个可用的 curl 请求

以下是一个完整、可直接复制调用的示例，用于提交一个基本任务。请将占位提示词替换为你自己的内容。

curl -X POST https://api.hiapi.ai/v1/images/generations \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1"
  }'

响应包含任务 id 和一个 status 字段。新提交的任务通常返回 queued 或 processing。保存该 id；你将在轮询步骤中使用它。如果收到 401，请检查 HIAPI_API_KEY 是否已在你的 shell 中导出。如果收到 422，请检查错误消息以定位有问题的字段。

用 Python 发送同样的请求

将 curl 调用移植到 Python，以便放入脚本或服务中。此示例使用 requests 并从环境变量读取密钥。

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/images/generations"

payload = {
    "model": "nano-banana-2-lite",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light, soft focus",
    "aspect_ratio": "1:1",
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"], job["status"])

将请求体保存在字典中，以便在不重写调用的情况下用可选字段扩展它。对于提交步骤，30 秒的超时是合理的，因为繁重的工作是异步进行的。

添加可选的参考输入

参考输入让你用视觉上下文来引导生成。在 HiAPI 上，你将它们作为同一 JSON 体中的 reference_images 数组附加。每个条目是公开可访问的 URL 或 base64 数据 URI。当你希望保留构图、匹配风格，或让产品图在多个变体间保持一致时，使用参考图。

{
  "model": "nano-banana-2-lite",
  "prompt": "Same layout, but in a warm sunset palette",
  "reference_images": [
    "https://example.com/reference/layout.png"
  ]
}

仅在参考图能提供有效信号时才包含它们。每个参考图都是需要传输的额外数据，可能会稀释简单的提示词。对于直接的文生图任务，完全省略该字段。当你确实使用参考图时，保持它们相关且数量少；一两张精心挑选的图片通常胜过一大组。

轮询异步结果

图片生成是异步的：你提交任务，然后轮询任务端点直到状态变为终态。在 curl 和 Python 中模式相同。

使用 curl 时，通过任务 id 检查任务：

curl https://api.hiapi.ai/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

在 Python 中，将轮询包装在带延迟的循环中，以免频繁请求 API：

import time

def wait_for_job(job_id, interval=2, max_attempts=30):
    url = f"https://api.hiapi.ai/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    for _ in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError("Job did not finish in time")

从较短的间隔开始，如果轮询大量任务则逐步退避。始终设置最大尝试次数，以免卡住的任务永久阻塞你的工作进程。将 failed 视为终态并记录错误消息。

下载并验证输出

当任务成功时，响应包含一个或多个输出 URL。获取该文件并保存到本地，然后验证你得到的内容。

result = wait_for_job(job["id"])
if result["status"] == "succeeded":
    image_url = result["output"]["url"]
    img = requests.get(image_url, timeout=60)
    img.raise_for_status()
    with open("output.png", "wb") as f:
        f.write(img.content)

对下载内容做基本检查：确认内容类型是图片，检查文件大小非零且合理，并打开一次确认它符合你的提示词。将任务 id 与本地文件名一起记录，以便将任何素材追溯到其请求。

投产前的成本与故障检查清单

Nano-Banana-2-Lite 定价为超低成本档位；计费遵循平台的标准图片生成计量。请查看网站上当前的价格面板以获取准确费率，而不是硬编码假设。

在上线之前，请养成以下习惯：

• 带退避的重试。 对瞬时错误（超时、5xx）重试少量次数并增加延迟；不要重试 4xx 验证错误。
• 限制轮询。 使用固定间隔和最大尝试次数。记录最终状态和耗时。
• 记录任务 id 和提示词。 将任务 id、提示词、模型以及任何参考输入与每个输出一起存储，以便重现或审计运行。
• 尽早验证输入。 提交前检查提示词长度和参考 URL，以避免浪费任务。

有了这些检查，Nano-Banana-2-Lite 就是用于批量和后台生成的可预测、低成本的主力工具。请浏览 HiAPI 上的模型页面以获取最新参数和费率详情。