博客

教程

如何通过 HiAPI API 使用 Nano-Banana:curl、Python 与可运行的请求

2026年11月12日
抽象的层叠半透明玻璃平面,把浅灰底色折射成冷蓝色带,用作教程封面图
本页内容

Nano-Banana 作为 API 能为开发者提供什么

Nano-Banana 是通过 HiAPI API 对外提供的图像生成模型。你发送提示词——如果需要,还可以附加一张或多张参考图——然后收到生成的图像。整体心智模型就这么简单。无需本地托管模型、无需准备 GPU、也无需学习额外的 SDK:你在使用其他 HiAPI 模型时所采用的鉴权方式、请求封装和异步任务机制在这里同样适用。

在写代码之前,先明确图像生成端点是什么、不是什么,会很有帮助。它是一个创意端点:同一个提示词在多次运行中可能产出不同结果,你应设计流水线来容忍这一点。它不像缩放或格式转换那样是确定性的转换。如果你需要像素级精确的可复现性,请把你验收通过的输出缓存下来,而不是假设重新生成会得到相同结果。

典型的集成分为三个阶段:

  1. 提交一个生成请求,附带提示词和任何可选输入。
  2. 等待生成的任务完成,因为图像生成比简单的文本补全耗时更长。
  3. 获取输出,将其存储,并决定是接受它,还是调整提示词后重试。

有两件事值得一开始就决定,因为它们会影响其他所有环节:你的提示词是纯文本还是使用参考图(这会改变请求载荷),以及你是否需要在多次生成中保持角色一致(这几乎总是意味着要使用参考图)。下面各节将从请求结构向外展开,你可以边看边调整示例。

Nano-Banana 请求的结构剖析

通过 HiAPI 调用 Nano-Banana 的每次请求骨架都相同。变化的只是载荷。

端点和鉴权

请求发往 HiAPI 的基础 URL,具体模型在请求载荷中指定,而不是在手工拼接的上游 URL 中指定。你通过 Authorization 请求头携带 API 密钥进行鉴权。请把密钥保存在环境变量中——绝不要内联在源代码里或提交到仓库。

模型名称

模型标识符是你 JSON 请求体中的一个字段。请把它当作需要从模型列表中逐字复制的字符串,而不是自己拼出来的东西,这样命名变更就不会悄无声息地破坏你的代码。

提示词载荷

你至少需要发送一个描述目标图像的文本提示词。在这里,提示词质量对输出质量的影响远大于其他任何字段。要具体说明主体、构图、光照和风格。模糊的提示词会生成模糊的图像,任何参数设置都救不回一个没有说清你真正需求的提示词。

可选参考图

如果你包含参考图,它们属于同一个请求体——通常以图像 URL 或编码后的图像数据提供,具体取决于模型接受的形式。参考图可以锚定角色的面部、服装或整体艺术风格等内容。纯文生图时省略它们;当输出需要与特定对象相似时再包含它们。

输出相关字段

有些字段影响的是结果形式而非内容:例如请求的输出尺寸或宽高比。最好把它们视为请求值,而非保证值——模型返回的尺寸可能略有差异。下游代码应读取实际返回的尺寸,而不是假设你请求的就是你得到的。

以下是概念上的结构,占位符值:

{
  "model": "<nano-banana-model-id>",
  "prompt": "一只红狐坐在金色时刻的高草丛中,浅景深",
  "reference_images": [],
  "size": "1024x1024"
}

请查阅该模型的参数文档以了解确切接受的字段名和格式——上述结构只是通用模式,不能替代规范文档。

可运行的 curl 请求

确认密钥可用、载荷有效的最快方式是执行一次 curl 调用。先设置环境:

export HIAPI_API_KEY="your-api-key-here"

然后提交生成请求:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<nano-banana-model-id>",
    "prompt": "一只红狐坐在金色时刻的高草丛中,浅景深",
    "size": "1024x1024"
  }'

各部分的作用:

  • URL — HiAPI 的图像生成路径。一个基础 URL 服务所有模型;模型在请求体中指定。
  • Authorization — 你的密钥,从环境读取,这样它不会进入 shell 历史记录或源码管理。
  • Content-Type — 必须是 application/json;常见的新手错误是忘记设置它,从而得到解析错误。
  • 请求体 — 上一节中的 JSON 载荷,其中包含你真正想要的提示词。

解读响应

响应会告诉你发生了什么。有两种结果值得关注:

  • 同步结果 — 有些调用会直接返回图像数据或图像 URL。如果你看到 URL,请尽快抓取并存储,而不要依赖它们长期可用。
  • 任务句柄 — 如果生成是异步的,响应会包含一个用于轮询状态的标识符。这就是下文异步部分的主题。

如果你想在响应体之外同时看到 HTTP 状态行和响应头,请在 curl 命令中加上 -i——当出错时,这对区分是鉴权问题还是载荷问题非常有用。

Python 中的相同调用

除了一次性脚本之外,请改用 Python。requests 库能让示例保持依赖轻量,并让 HTTP 层显式可见。

import os
import requests

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

payload = {
    "model": "<nano-banana-model-id>",
    "prompt": "一只红狐坐在金色时刻的高草丛中,浅景深",
    "size": "1024x1024",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)

从一开始就应养成的几个习惯:

  • 设置超时。 图像生成较慢;没有超时,你的工作进程可能无限期挂起。对于同步调用,较宽松的超时是合理的起点,但请根据你的负载调整。
  • 使用 raise_for_status()。 它能把 4xx 和 5xx 响应转换为可捕获的异常,而不是默默把错误响应体当作结果来解析。
  • 封装成函数。 上面的代码片段是一个脚本;在服务中,你会需要一个接收提示词并返回图像数据或任务句柄的函数,这样你的其他代码就不必关心 HTTP 细节。

如果响应包含图像 URL,请立即下载并存储:

for item in data.get("data", []):
    url = item.get("url")
    if url:
        img = requests.get(url, timeout=60)
        img.raise_for_status()
        with open("output.png", "wb") as f:
            f.write(img.content)

你的应用程序的真实数据源应是你自己的存储——而不是临时的远程 URL。

处理异步任务

图像生成通常耗时超过单次 HTTP 往返应保持连接的时间。采用这种方式的 HiAPI 模型在你提交时会返回一个任务标识符,然后你轮询任务状态端点,直到作业完成。该模式适用于平台上所有异步模型,所以学一次即可。

先提交,再轮询

你最初的 POST 会返回类似任务 ID 的内容。然后你用该 ID 轮询状态端点。你需要的逻辑是:

import time

def poll_task(task_id, api_key, interval=2, max_wait=300):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"https://api.hiapi.ai/v1/tasks/{task_id}",
            headers=headers,
            timeout=30,
        )
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("succeeded", "completed", "failed", "error"):
            return body
        time.sleep(interval)
    raise TimeoutError(f"任务 {task_id} 在 {max_wait} 秒内未完成")

三条能让你少踩坑的规则

  1. 始终限制总等待时间。 永远不完成的作业不能让你的工作进程卡死。上面的 max_wait 就是你的退出通道。
  2. 退避。 固定短间隔对交互式使用没问题;对于批处理作业,随着等待时间增长而增大间隔,以免频繁冲击状态端点。
  3. 验证终态。 succeeded 表示你可以读取输出;failed 表示你应读取错误载荷,而不是盲目重试。重试格式错误的载荷只会浪费时间。

把任务 ID 与你自己的作业记录一起持久化。如果你的进程在轮询中途重启,你可以继续轮询,而不用重新提交并为重复生成付费。

参考图与角色一致性

纯文本提示词对于一次性图像没问题,但当你需要在十个不同场景中出现同一个角色时,它们就力不从心了。用文字描述一张脸,然后指望模型稳定复现,几乎不会奏效——措辞的细微变化会生成不同的人。

参考图能解决这个问题。你在请求中随文本提示词一起包含一张或多张图像,模型将它们用作视觉锚点。角色一致性是核心用例:

  • 角色设定表 — 一张干净的参考图,多个场景提示词,保持一致的面部和服装。
  • 风格锚定 — 参考图设定视觉语言,提示词引导内容。
  • 产品图 — 物体的参考图使其设计在不同背景下保持稳定。

在请求中,这意味着要填充参考图字段,而不是发送空值。以 URL 或编码数据形式提供图像,具体取决于模型参数规范支持哪种,并保持参考图干净:一个清晰的主体胜过一个杂乱的场景,因为模型会抓住画面中的所有东西,而不仅仅是你关心的部分。

流水线的一个实用模式:

  1. 从详细的文本提示词生成一次角色。
  2. 审阅它,接受或重新生成,直到满意。
  3. 将该验收通过的图像用作后续每个场景的参考图。

这就是 nano banana API python 工作流的缩影:先把角色锁定一次,然后只改变提示词中场景部分。要预期迭代——参考图能提升一致性但无法做到完美,所以要构建审阅步骤,而不是假设每张输出都可用。

输出分辨率与实际限制

分辨率是最容易因假设而出问题的地方,所以要谨慎对待。

请求尺寸与实际尺寸

你可以请求输出尺寸,但应把它当作提示。模型返回的尺寸可能与你请求的不同——尤其对于不常见的宽高比。稳健的做法是读取你实际收到的图像尺寸并做通用处理:你的存储、缩略图和布局都应基于真实文件,而不是请求值。

质量由什么驱动

输出质量主要由提示词决定,以及在使用时由参考图决定。一个构图良好、主体和光照清晰的提示词,比一个模糊但请求更大尺寸的提示词能产出更好的图像。不要用分辨率来弥补描述不充分的提示词。

围绕限制做规划

  • 不要硬编码尺寸 到下游代码中。从返回的图像中读取它们。
  • 存储前先验证。 如果你的应用要求最小尺寸,请在生成后检查实际尺寸;如果不足则重新生成——不要假设请求已强制满足该要求。
  • 注意文件大小。 更高分辨率的输出意味着更大的载荷;应流式或缓冲下载,而不是在循环中把所有内容加载到内存。
  • 谨慎批处理。 并发限制按账户计;如果你要生成大量图像,请增加一个小的 worker 池并带退避重试,而不是在无界循环中狂发请求。

要了解 Nano-Banana 的权威能力和可接受值,应参考该模型的文档——而不是本文中的示例载荷。计费遵循平台正常的按用量计费方式,当前费率请见价格面板,而不是本教程。

排查常见错误

大多数首次集成失败属于几类情况。以下是每类的检查要点。

401 / 403 — 鉴权

你的密钥缺失、格式错误或未被发送。确认 Authorization 头存在,带有 Bearer 前缀,并且环境变量确实已导出到运行代码的 shell 或进程。复制密钥时末尾多出的换行符导致此问题的频率比你预期的高。

400 — 载荷格式错误

通常是以下之一:无效 JSON(多余的引号或尾随逗号)、错误的 Content-Type、缺少必需字段(如 prompt 或 model),或参考图字段以模型不接受的格式发送。打印你实际发送的确切请求体,并逐字段与参数规范对比。

404 — 路径或模型错误

端点路径错误,或模型标识符与平台上任何模型都不匹配。请从列表中原样复制模型名称,而不要凭记忆输入。

超时与轮询停滞

对于同步调用,过短的超时会中断本可成功的作业。对于异步作业,轮询停滞通常意味着你的轮询逻辑提前退出,或终态检查与 API 实际返回的状态字符串不匹配——请记录原始状态值并核实。始终保留最大等待时间,使卡住的作业大声失败而不是挂起。

空结果

返回 200 但没有图像,几乎总是内容问题而非 bug:提示词可能太模糊,也可能被过滤了。在认定 API 出错之前,先检查响应体中的错误或原因字段,然后收紧并澄清提示词。

重试时失败

如果同一载荷有时成功有时失败,你很可能触发了速率限制或遇到瞬时服务器错误。在提交和轮询周围添加指数退避,并且不要重试 400——应修正载荷。

如有疑问,最快的诊断方法是用一个简单提示词发起一次最小化 curl 调用。如果它能工作,问题就在你的载荷或代码中,而不是凭据。

立即开始构建持久 AI 产物

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

阅读 API 文档