博客

教程

如何通过 HiAPI API 使用 nano-banana-2:可用的 curl 与 Python Requests 示例

一份开发者指南,教你将 nano-banana-2 接入图像生成流水线

2026年11月12日
简约封面图:暖沙底色上,赤陶色与棕褐色水平阶梯条带如水银柱图般向下错落排列。
本页内容

nano-banana-2 能为你做什么,以及何时该用它

nano-banana-2 是一个以 HTTP API 方式调用的图像生成模型。你发送一段提示词,可选地附带一张源图,然后拿回一张生成的图像。这就是你在写代码前需要的全部心智模型。

当你需要在既有产品或流水线中以编程方式生成图像,而不是通过聊天窗口操作时,就该用 nano-banana-2:营销素材生成、缩略图与封面制作、基于底图的迭代修改,或者图像数量由你自己的数据驱动的批处理任务。由于它的接口就是普通的请求/响应式 API,你可以把它放在队列 worker、后端接口或 CLI 工具后面,而无需为每种语言引入新的 SDK。

两种模式覆盖了大多数用例:

  • 文生图——你用提示词描述想要的内容,然后得到图像。
  • 图生图——你提供一张源图,再加一段描述变换的提示词,然后拿回修改后的图像。

两种模式的请求形状相同,因此一个客户端封装(本文稍后会构建)就能同时处理两者。如果你的流水线只从文本渲染,完全可以忽略 image 字段。如果你的流水线是关于编辑已有素材的,那么图生图就是你的入口。

nano-banana-2 不 替你做的事:它不管理你的重试、超时、存储或幂等性。这些是你围绕调用构建的部分——而这正是本教程其余大部分内容的重点,因为在一个循环里天真地调用 requests.post,是“demo 能跑、生产不行”最常见的原因。

发送第一个请求之前

首次调用前,你需要准备好三件事。

1. 平台凭据

你需要从 HiAPI 平台获取 API 访问权限,以及分配给你账号的凭据。请把它当作机密处理:从环境变量或密钥管理器中加载,绝不要提交到代码仓库,也绝不要粘贴到客户端打包产物中。下面的每个请求都从环境变量读取密钥,因此源代码中不会出现任何敏感信息。

export HIAPI_API_KEY="your-key-here"

2. 客户端环境

使用 curl 的话,你只需要一个能运行 curl 的 shell——示例使用的是标准构建自带的参数。使用 Python 的话,你需要 Python 3 和 requests 库:

python3 -m venv .venv
source .venv/bin/activate
pip install requests

3. 存放输出的地方

图像生成会返回图像数据——具体是内联在响应中,还是作为之后可获取的引用,取决于你账号返回的响应形状。请提前决定你是要把字节保存到磁盘、上传到对象存储,还是返回一个 URL 给调用方。现在就考虑清楚,可以避免经典的“在 shell 里能跑,但我没地方放文件”的尴尬时刻。

开始上手并不需要估算限额或价格。首次集成的通用原则是:发送最小的有效请求,确认你能得到有效响应,然后再添加参数。下一节正是这么做的。

一个可用的最小 curl 请求

下面是一个完整的文生图调用。端点、请求头和请求体是仅有的可变部分:端点标识 HiAPI 平台上的模型与操作,请求头携带你的凭据,JSON 请求体携带载荷。

curl -sS -X POST "$HIAPI_BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "a minimalist isometric workspace, soft daylight, muted palette",
    "n": 1
  }'

把 HIAPI_BASE_URL 设置为你的 HiAPI 账号仪表盘中显示的 API 基础地址,这样就不会把主机名硬编码进脚本。请求体有三个字段,三者都很重要:

  • model 告诉平台运行哪个模型。即使你在别处使用了默认值,也请显式保留它;这能让日志本身说明问题。
  • prompt 是自然语言。要具体描述主体、构图和风格;含糊的提示词会产生含糊的图像。
  • n 是为此提示词请求的图像数量。在验证链路是否通畅时,先从 1 开始。

成功的响应会在响应体中返回图像数据。在编写任何解析器之前先检查它:把输出通过 jq 管道处理,或重定向到文件,然后查看顶层键。你正在确认两件事——请求被接受了,以及图像载荷实际位于响应中的哪个位置。

不要在首次调用时急于添加参数。一个你理解的可运行基线,胜过一份你抄来的庞大请求体。一旦这个调用能返回图像,后面每一节都是它的变体。

同样的请求,用 Python 写

把 curl 调用移植到 Python,但不改动载荷。保持单一事实来源(一个 dict)意味着你在 shell 中验证过的请求体,就是你最终上线的请求体。

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]


def generate_image(prompt: str, model: str = "nano-banana-2", n: int = 1,
                   timeout: float = 60.0) -> dict:
    """发送一次文生图请求并返回解析后的 JSON 响应。"""
    payload = {"model": model, "prompt": prompt, "n": n}
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = generate_image(
        "a minimalist isometric workspace, soft daylight, muted palette"
    )
    print(result.keys())

有三个细节值得强调,因为它们是人们抄代码片段时最容易漏掉的部分。

始终设置 timeout。 不设置的话,一个卡住的连接会无限期阻塞你的 worker。上面的值只是起点,不是铁律——请根据你实际观察到的延迟来调整。

使用 json= 而不是 data=。 把 dict 传给 json 会正确设置内容类型并序列化;把原始字符串传给 data 正是你遇到看似模型故障的请求体格式错误的原因。

在解析前调用 raise_for_status()。 对一个 4xx 响应尝试用 .json() 解析成图像字段,会产生令人困惑的下游错误。先暴露 HTTP 状态码。

这个函数就是前面提到的可复用封装。下一节会扩展它的载荷,而不是替换它。

文生图与图生图的载荷

两种模式的区别只有一处:请求体是否包含源图。其他一切——端点、认证头、模型名称——都保持不变。

文生图

{
  "model": "nano-banana-2",
  "prompt": "a minimalist isometric workspace, soft daylight",
  "n": 1
}

图生图

{
  "model": "nano-banana-2",
  "prompt": "same scene, but converted to a warm evening palette",
  "image": "<base64-encoded source image>",
  "n": 1
}

需要内化的概念:在图生图模式下,提示词描述的是变换,而不是从头描述完成的场景。“转换为温暖的傍晚色调”比重新描述整张图更好,因为源图已经提供了内容。

关于 image 字段的两点实用说明:

  • 按照 API 为该字段文档规定的格式对源图进行编码,并让编码后的载荷远低于你的请求大小预算。过大的输入是请求被拒的主要原因之一。
  • 如果你打算接受用户上传,请在编码之前校验大小和格式。在你这边快速失败,远比一次以 4xx 结束的往返便宜得多。

为 Python 封装添加一个可选的 image 参数,一个函数就能服务两种模式:

def generate_image(prompt: str, image: str | None = None, **kwargs) -> dict:
    payload = {"model": "nano-banana-2", "prompt": prompt, **kwargs}
    if image is not None:
        payload["image"] = image
    # ... 与之前相同的请求调用

因为分支只是一个 if,你的调用代码决定模式,而传输层保持不变。这就是保持单一封装的回报。

处理异步任务与重试

图像生成可能比典型的 JSON API 调用耗时更长。有些响应会立即返回完成的图像;另一些则返回一个任务,你必须轮询才能拿到结果。即使你第一次成功的调用是立即返回的,也要为轮询场景设计——否则当某次生成耗时过长时,你的流水线就会崩溃。

一个稳健的模式包含三部分:带退避的轮询循环、硬性截止时间,以及区分“尚未就绪”和“失败”的重试策略。

import time
import requests


def poll_job(job_id: str, base_url: str, api_key: str,
             initial_wait: float = 2.0, max_wait: float = 30.0,
             deadline: float = 300.0) -> dict:
    start = time.monotonic()
    wait = initial_wait
    while True:
        if time.monotonic() - start > deadline:
            raise TimeoutError(f"job {job_id} exceeded deadline")

        response = requests.get(
            f"{base_url}/v1/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30.0,
        )
        response.raise_for_status()
        body = response.json()

        status = body.get("status")
        if status == "succeeded":
            return body
        if status == "failed":
            raise RuntimeError(f"job {job_id} failed: {body}")

        time.sleep(wait)
        wait = min(wait * 2, max_wait)

任务路径和状态词表应与你的 HiAPI 账号 API 参考所规定的保持一致——把上面的键调整为对应形状,但保留结构。

让它在生产环境中保持健康的规则:

  • 指数退避并设置上限。 每 200 毫秒轮询一次浪费配额并冲击端点;将等待时间翻倍并设置上限,会稳定在真实完成时间附近。
  • 限制总尝试次数和总时间。 deadline 不可协商。无界循环就是在等待某个慢日引发故障。
  • 只重试可重试的错误。 瞬时网络错误和 5xx 响应值得带抖动再试一次;4xx 响应则不——重发格式错误的载荷只会浪费时间。使用小的有界重试次数(两到三次),并记录每一次。
  • 让重试安全。 如果你的任务创建端点接受幂等键,请为每个逻辑请求发送一个稳定的键,这样重试提交不会产生重复生成。

有了截止时间、退避和有界重试次数,一次缓慢的生成就变成了被记录、被处理的事件,而不是挂起的 worker。

调试你实际会遇到的错误

当调用失败时,先读取原始状态码和完整响应体,再动任何一个模型参数。响应体通常会指明问题。猜测比记录日志更慢。

认证失败

401 或 403 几乎总是意味着以下之一:环境变量中缺少密钥、请求头格式错误,或者凭据在此环境中未激活。检查你实际发送的请求头字面值——缺少 Bearer 前缀,或从复制的密钥中带入多余换行,都是常见原因。

载荷错误

400 并带有关于请求体的消息,意味着 JSON 本身有错:缺少 prompt、多余的逗号、Python 中用了 data= 而不是 json=,或者 image 字段编码不正确。把你发送的确切字节打印一次,检查,然后移除打印。

输入被拒

未通过校验的图生图请求通常与输入图像有关:太大、格式错误或无法解码。在发送前于你这边校验大小和编码,并向提供图像的人返回清晰的错误,而不是重试。

超时与 5xx

这些属于可重试类别。在日志中区分连接超时与服务器错误,并确认你的重试有上限——否则持续的 5xx 会变成无限循环。

一套有效的排查顺序

  1. 为每次失败记录 HTTP 状态码和原始响应文本。
  2. 首先验证凭据路径,先于其他一切。
  3. 用 curl 重放失败的载荷,把你的客户端代码从方程中移除。
  4. 只有在这之后,才调整 prompt、image 或其他模型参数。

如果失败在全部四步后仍然存在,从响应中捕获请求 ID(或等效的关联字段),并在联系支持时附上它——这能把一份含糊的报告变成可追踪的内容。

让它达到生产就绪

上线前,请过一遍这份检查清单。

  • 机密: API 密钥从环境变量或密钥管理器加载,且不出现在任何日志、错误消息和客户端打包产物中。
  • 超时: 每个 HTTP 调用——创建、轮询以及获取结果图像——都有显式超时。
  • 边界: 轮询有截止时间,重试有最大尝试次数,代码中区分可重试与不可重试的失败。
  • 可观测性: 为每次调用记录请求形状(如果提示词可能包含用户数据,则省略或哈希)、状态码、延迟和关联 ID。
  • 成本意识: 计费遵循你的 HiAPI 账号定义的维度,因此要跟踪每个请求产生多少次生成和多少输出,并为自己的用量计数器埋点,让失控循环在账单之前就可见。
  • 存储: 生成的图像写入持久化位置——对象存储或数据库——而不是留在随容器消失的临时目录中。

这些条目没有一项是 nano-banana-2 特有的。这正是重点:模型调用是简单的部分,围绕它的一切都是普通的分布式系统卫生。构建一次封装,把载荷保存在一个 dict 中,文生图和图生图就都免费获得了。

从 curl 调用开始,把它移植到 Python 封装,添加轮询循环,然后运行检查清单。有关模型详情和最新 API 参考,请参阅 HiAPI 平台上的 nano-banana-2 文档。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档