博客

教程

Nano-Banana-2 API 教程:通过 hiapi 使用可正常工作的 curl 与 Python Requests

2026年11月10日
平铺封面艺术:错落排布的骨白色纸张,层叠边缘为炭黑色,其中一张为锈红色,16:9。
本页内容

首次调用前的准备工作

向 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 无需登录即可在浏览器中直接加载,并在发送前对照限制检查文件类型和大小。

一套有效的调试顺序

  1. 字面地阅读错误信息和状态码——它们通常会点明问题。
  2. 用最少的字段在 curl 中复现失败的请求,然后逐步加回复杂度。
  3. 在处理之前打印完整的响应体;不要依赖你对它结构的假设。

如果最小化的 curl 调用能成功而你的应用失败,那么缺陷在你的代码中,而不是 API。这是你所能做的最快的诊断分界。

将其接入你的应用

一个可用的请求是好的开始;可靠的集成需要在其周围多一些东西。下面是如何从一次性调用过渡到可以依赖的东西。

把调用封装成函数

把请求隔离在一个函数中,它接收提示词(可选接收参考图)并返回结果。把请求头、基础 URL 和请求体构造都放在该函数内部,这样代码库的其他部分永远不接触它们。当 API 变化时,你只需编辑一处。

有意识地处理重试

生成可能因与你的请求体无关的原因而暂时失败。使用指数退避重试,但只对可重试的失败——超时和某些服务器端错误。绝不重试认证或请求体验证错误;它们每次都会以相同方式失败,只会增加负载。限制尝试次数,让持续存在的问题暴露出来,而不是一直挂起。

超时与并发

设置一个对生成足够宽裕但有上限的超时,并在测量真实响应时间后调整它。如果你要发出大量请求,请遵守合理的并发限制,而不是一次性全部发出——带工作池的队列比无限制的并行调用更可预测。

存储你生成的内容

响应会给你生成的图像。及时将其复制到你自己的存储中,而不是依赖返回的 URL 无限期有效。以确定性的方式命名文件,并在每个输出旁记录提示词和参数——以后迭代提示词时你会需要这份溯源信息。

让密钥远离代码

在每个环境中从环境变量或密钥管理器读取 API 密钥。定期轮换密钥。如果密钥出现在不该出现的地方,在仪表盘中撤销它。

从小处开始,再扩展

让一个提示词在 curl 中跑通,移植到 Python,添加上一节的错误处理,然后才构建周围的队列和存储。每一步都为前一步提供证明。

有了经验证的 curl 调用、匹配的 Python 客户端,以及处理好的三类错误,你就拥有了从首次请求到生产集成的完整路径。

立即开始构建持久 AI 产物

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

阅读 API 文档