教程
Nano-Banana-2 API 教程:通过 hiapi 使用可正常工作的 curl 与 Python Requests
本页内容
首次调用前的准备工作
向 Nano-Banana-2 发送任何请求之前,先把四样东西准备好。它们都不会花太多时间,而把四样全部备齐,首次请求就变成一次复制粘贴练习,而不是一场寻宝。
1. hiapi 账户和 API 密钥
每个请求都通过与你的 hiapi 账户绑定的 API 密钥进行认证。在账户仪表盘中创建密钥,并存放在安全的地方——密码管理器,或你机器上的环境变量。像对待密码一样对待它:绝不提交到代码仓库,也不要粘贴到共享文档中。
在你的机器上,每个 shell 会话导出一次,这样下面的示例无需硬编码任何内容就能读取它:
export HIAPI_API_KEY="your_api_key_here"
2. API 基础 URL
基础 URL 是所有请求构建所基于的根地址。构造端点时,你把模型路由追加到它后面。把基础 URL 放在代码中的配置变量里,而不是分散在多个文件中——这样一旦它发生变化,你只需改一行。
3. 发送请求的客户端
开始时你只需要以下其中一种:
- curl —— 几乎肯定已经安装好了。在编写任何应用代码之前,用它来确认你的密钥和请求体是正确的。
- Python 3 加
requests库(pip install requests)。大多数读者会用这个来构建真正的集成。
两者都备着很有用:curl 能把请求与你的代码隔离开,所以如果出问题,你就能知道问题出在 API 调用还是应用上。
4. 清楚自己要生成什么
Nano-Banana-2 同时支持文生图和图生图。提前决定你需要哪种模式,因为请求体的结构不同(后文会详细说明)。第一次调用时,从文生图开始——它的可变因素最少。
密钥已导出、客户端已安装、提示词也想好了,现在就可以来看请求本身了。
Nano-Banana-2 请求的组成部分
Nano-Banana-2 调用是一个带 JSON 请求体的 POST 请求。每个字段各司其职,分开理解它们,意味着出问题时你可以一次只改一处。
端点
请求会发往 hiapi API 基础 URL,并追加 Nano-Banana-2 模型路由。方法始终是 POST,因为你是在发送一个待处理的负载,而不是获取资源。
请求头
有两个请求头很重要:
Content-Type: application/json—— 告诉 API 如何解析你的请求体。Authorization—— 携带你的 API 密钥。下面的示例会从你之前导出的环境变量中读取它。
如果任一请求头缺失或格式错误,请求在模型看到它之前就会失败。这是造成令人困惑的错误的最常见单一来源。
请求体字段
文生图请求携带以下字段:
model—— 指定要运行的模型是 Nano-Banana-2。即使存在默认值,也请显式写明;这能让你的代码自我说明,并在默认值变化时保护你。prompt—— 用自然语言描述你想要的图像。你大部分的迭代工作都会发生在这里。要具体:主体、构图、风格、光线。模糊的提示词会产生模糊的结果。- 图像输入 —— 文生图时为缺省或空。图生图时,它携带你的参考图(图生图部分有更多说明)。
- 输出与尺寸参数 —— 模型特有的字段,影响返回结果的形状或比例。只设置模型文档标明支持的字段;在严格 API 中,未知字段通常意味着请求被拒绝,而不是被无声忽略。
返回内容
响应是 JSON。取决于调用如何构造,你会直接收到生成的图像数据,或收到对它的引用。你的客户端代码应先检查 HTTP 状态,再查看返回的请求体——不要假设一个 200 形态的响应就一定包含图像而不加以验证。
整个结构就是这些:一个带少量显式 JSON 请求体的认证 POST 请求。本教程其余内容都只是这个形态的变体。
一个可用的 curl 请求
这是你能发出的最小完整调用。在已导出 API 密钥的终端中运行它,几秒钟内你就能知道账户、密钥和网络路径是否都工作正常。
curl -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition"
}'
在 shell 中与密钥一起设置一次基础 URL:
export HIAPI_BASE_URL="https://api.hiapi.ai"
(使用你的 hiapi 仪表盘中显示的基础 URL——那才是你账户的权威值。)
读取输出
curl 会把原始响应打印到 stdout。如果调用成功,你会看到包含生成图像的 JSON。用 python -m json.tool 管道处理它,以美化输出并确认结构:
curl -s -X POST "$HIAPI_BASE_URL/nano-banana-2" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-d '{"model":"nano-banana-2","prompt":"a red fox in fresh snow, side profile, crisp detail"}' \
| python -m json.tool
解读你看到的内容
- 成功的响应——确认你的密钥有效、端点正确、请求体能被解析。保存这个可用的命令——它是你的基线。
- 错误响应——说明三行请求头或请求体中有地方不对。复制错误文本;调试部分会把常见的错误映射到修复方法。
从 curl 开始的价值在于隔离。你的密钥、请求头和 JSON 都集中在一处可见,因此失败指向的是请求本身,而不是你的应用代码。一旦这个命令能正常工作,移植到 Python 就是机械性的工作。
同样的请求用 Python 实现
下面是用 requests 实现的相同调用。请求体就是你在 curl 请求体中看到的同一个 dict——API 本身没有任何变化,变化的只是你发送它的方式。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
payload = {
"model": "nano-banana-2",
"prompt": "A weathered cabin on a rocky coastline at dawn, low fog, soft warm light, wide composition",
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {API_KEY}",
}
response = requests.post(
f"{BASE_URL}/nano-banana-2",
json=payload,
headers=headers,
timeout=120,
)
response.raise_for_status()
data = response.json()
print(data)
为什么这样写
json=payload让requests为你序列化 dict 并设置Content-Type。你仍然可以显式传入该请求头;这没有坏处,还能让请求自我说明。timeout=120—— 图像生成不是瞬时的。宽裕的超时能防止客户端在模型还在工作时就放弃。根据你的用例调整这个值。raise_for_status()把非 2xx 响应转为异常,这样失败会立即暴露,而不是悄悄流入你的结果处理代码。- 环境变量让密钥远离源码。在生产环境中,从平台的密钥存储注入它,而不是使用可能被提交的
.env文件。
提取图像
响应体是 JSON。先交互式地查看一次,了解确切的结构,然后显式地取出图像字段:
image_url = data["image_url"] # confirm the key name against a real response
如果你的响应携带的是 base64 数据而不是 URL,解码并写入:
import base64
with open("output.png", "wb") as f:
f.write(base64.b64decode(data["image_base64"]))
不要猜字段名——在第一次成功调用时打印原始响应,并依据实际存在的内容取值。这一个习惯就能防止大多数集成缺陷。
文生图与带参考图的图生图
到目前为止都是文生图:输入提示词,输出图像。Nano-Banana-2 也支持图生图,你需要提供一张参考图,模型将其作为指导。知道何时切换模式,以及请求体如何变化,就是调用成功与被拒绝之间的区别。
何时使用每种模式
- 文生图 —— 你有用文字表达的想法,没有起始图像。最适合探索、插画,以及任何从零生成的内容。
- 图生图 —— 你有现成的图像,想要一个变体、重新风格化,或保留其结构或主体的编辑。这是用于迭代设计、匹配视觉风格或转换照片的模式。
如果你的提示词是“让它看起来像……”或“保持布局但……”,那你需要图生图。
参考图如何改变请求
端点和请求头保持不变。变化的是请求体:你在提示词旁边添加一个参考图字段。取决于图像如何提供,该字段携带 URL 或编码的图像数据。请记住这些规则:
- 如果传链接,请使用可直接公开访问的 URL。需要登录或通过认证重定向的页面会失败——API 需要直接获取字节。
- 匹配预期格式。 PNG 和 JPEG 等常见格式是安全的;异常或损坏的文件是请求被拒绝的常见原因。
- 上传前检查大小限制。 大图像常常是请求体错误的原因。
- 保持提示词聚焦。 有参考图时,描述你想要的转换,而不是重新描述参考图。
一个示意性的图生图请求体如下:
payload = {
"model": "nano-banana-2",
"prompt": "Same subject, restyled as a graphite sketch with light crosshatching",
"image_url": "https://example.com/your-reference.jpg",
}
一如既往,请用你第一次成功响应来确认确切的字段名。原则很简单:文生图只有提示词,图生图在相同的请求形态上添加经过验证的参考图。先用文生图证明流程可行,然后再叠加参考图。
处理错误与调试失败请求
Nano-Banana-2 调用失败归结为三类。学会识别每一类,你就能在一分钟内修复大多数问题。
认证错误
如果你看到认证错误,说明密钥没有正确到达 API。按顺序检查:
HIAPI_API_KEY是否确实在运行请求的 shell 或环境中导出?运行echo $HIAPI_API_KEY确认。Authorization请求头是否存在且格式正确?方案和密钥都很重要。- 密钥是否已在仪表盘中撤销或轮换?
- 你是否在访问你账户的正确基础 URL?
401 或 403 几乎总是意味着这四种情况之一。密钥本身很少是问题——围绕它的管道通常才是。
请求体格式错误
400 类错误通常意味着 API 无法解析或验证你的请求体:
- 无效 JSON —— 多余的逗号、用单引号代替双引号,或未转义的字符。把 curl 输出管道给
python -m json.tool,以及在代码中而不是手工构建请求体,都有帮助。 - 缺少必需字段 ——
model和prompt是你最常忘记的;每次都要显式发送两者。 - 未知或不支持的字段 —— 严格的 API 会拒绝它们不认识的字段。移除所有多余内容直到请求通过,然后一次加回一项。
- 错误的值类型 —— 数字以字符串发送,或期望单个值的地方传入数组。严格匹配文档中的类型。
糟糕的图像输入
只与图生图相关,但发生时最令人沮丧:需要认证的图像 URL、位于重定向之后的 URL、返回 HTML 而不是图像的 URL、尺寸过大,或格式不支持。确认 URL 无需登录即可在浏览器中直接加载,并在发送前对照限制检查文件类型和大小。
一套有效的调试顺序
- 字面地阅读错误信息和状态码——它们通常会点明问题。
- 用最少的字段在 curl 中复现失败的请求,然后逐步加回复杂度。
- 在处理之前打印完整的响应体;不要依赖你对它结构的假设。
如果最小化的 curl 调用能成功而你的应用失败,那么缺陷在你的代码中,而不是 API。这是你所能做的最快的诊断分界。
将其接入你的应用
一个可用的请求是好的开始;可靠的集成需要在其周围多一些东西。下面是如何从一次性调用过渡到可以依赖的东西。
把调用封装成函数
把请求隔离在一个函数中,它接收提示词(可选接收参考图)并返回结果。把请求头、基础 URL 和请求体构造都放在该函数内部,这样代码库的其他部分永远不接触它们。当 API 变化时,你只需编辑一处。
有意识地处理重试
生成可能因与你的请求体无关的原因而暂时失败。使用指数退避重试,但只对可重试的失败——超时和某些服务器端错误。绝不重试认证或请求体验证错误;它们每次都会以相同方式失败,只会增加负载。限制尝试次数,让持续存在的问题暴露出来,而不是一直挂起。
超时与并发
设置一个对生成足够宽裕但有上限的超时,并在测量真实响应时间后调整它。如果你要发出大量请求,请遵守合理的并发限制,而不是一次性全部发出——带工作池的队列比无限制的并行调用更可预测。
存储你生成的内容
响应会给你生成的图像。及时将其复制到你自己的存储中,而不是依赖返回的 URL 无限期有效。以确定性的方式命名文件,并在每个输出旁记录提示词和参数——以后迭代提示词时你会需要这份溯源信息。
让密钥远离代码
在每个环境中从环境变量或密钥管理器读取 API 密钥。定期轮换密钥。如果密钥出现在不该出现的地方,在仪表盘中撤销它。
从小处开始,再扩展
让一个提示词在 curl 中跑通,移植到 Python,添加上一节的错误处理,然后才构建周围的队列和存储。每一步都为前一步提供证明。
有了经验证的 curl 调用、匹配的 Python 客户端,以及处理好的三类错误,你就拥有了从首次请求到生产集成的完整路径。