使用指南

Nano Banana API 指南：在 HiAPI 上调用 nano-banana、nano-banana-2 和 nano-banana-pro

模型选项、提示词模式，以及在 HiAPI 上可用的图像生成请求

2026年11月3日

Nano Banana 模型家族能提供什么

图像生成很少只停留在一个设置上。项目早期你需要快速草稿来探索想法；后期你需要精细渲染来交付。HiAPI 上的 Nano Banana 家族正是围绕这一现实构建的：一个接口，三种变体，各自针对质量与速度曲线上的不同位置进行调优。

命名是有意为之的。nano-banana 是基础选项——当你在塑造提示词或布局时仍需要快速视觉反馈，就用它。nano-banana-2 在保真度和提示词遵循度上更进一步，通常是输出接近最终但你还想继续迭代时的选择。nano-banana-pro 是该家族中保真度最高的变体，适合细节和构图最重要的最终渲染。

它们共享的部分与它们不同的部分同样重要。三者都通过同一个 HiAPI 端点调用。你只需认证一次、构造一次请求，切换时只改模型标识符。这意味着应用可以在基础模型上发起请求，之后在更强的变体上重跑同一提示词，而无需改动传输层代码。

这样的家族也让你的架构保持简单。不必为每个质量层级接入独立的提供商，而是保留单一客户端、单一错误处理路径和单一的用量观测点。模型选择成为一个参数，而不是一次集成。

为什么是一个家族而非单个模型

工作流中的不同步骤有不同需求。提示词探索、布局草稿和客户预览看重速度；主视觉图和营销素材看重保真度。将模型选择视为运行时决策，可以让你把每个步骤匹配到合适的变体，而无需重建流水线。

在 nano-banana、nano-banana-2 和 nano-banana-pro 之间选择

通过问两个问题来选择变体：这个输出距离最终版本有多近，需要多少次尝试才能达到？其余问题都由此决定。

nano-banana：用于批量和探索

当你还在决定图像应该是什么样子时，使用基础模型。提示词改写、风格测试和布局缩略图都能从快速周转中受益，而粗略的渲染往往比一段描述更能回答你的问题。在开发期间将它保留为默认选项。

nano-banana-2：用于接近最终的迭代

当构图稳定、你正在精修细节——间距、主体保真度、输出对提示词的遵循紧密程度——时，切换到 nano-banana-2。这是务实的中间选择：遵循度明显更强，而不必为每次预览都走最高保真度路径。

nano-banana-pro：用于最终渲染

将 nano-banana-pro 保留给要交付的输出。主视觉图、产品图和任何客户会仔细查看的内容都值得使用更强的变体。不要将它设为默认——把它留给最后一步，让你的探索性迭代保持低成本。

一条实用的路由规则

一套简单的升级策略适用于大多数团队：

所有新提示词默认使用 nano-banana。
当结构正确但质量不够时，将提示词升级到 nano-banana-2。
提示词锁定后，在 nano-banana-pro 上运行最终版本一次。

这让迭代快速且可预测，也让你的用量模式易于理解。计费跟随用量且因变体而异，因此请在实时模型文档中确认当前费率和限制，而不是将任何数字硬编码到代码中。

跨变体通用的提示词模式

你能做的最昂贵的事情，就是写出只在一个模型上有效的提示词。让它们的结构支持一行改动即可切换。

四块式提示词

将每个提示词写成四个带标签的部分，按此顺序：

主体——图像中有什么，平实地陈述。
风格——视觉处理方式：照片、插画、水彩、3D 渲染。
构图——取景、相机角度、位置、负空间。
约束——要避免什么以及任何硬性要求。

一个填写好的示例：

Subject: a ceramic coffee mug on a wooden desk, steam rising
Style: soft natural light, shallow depth of field, editorial photography
Composition: centered, 50mm equivalent, generous negative space at top
Constraints: no text, no logos, neutral background

由于各块相互独立，你可以强化风格或放宽构图而无需重写整个提示词——而且同样的结构对该家族中的每个变体都很容易理解。

让提示词与模型无关

避免使用假定某个特定模型特性的措辞。描述你想要的结果，而不是某个具体模型应采取的步骤。当你需要比较变体时，只改模型 ID，并保持提示词逐字节一致，这样比较才有意义。

像管理代码一样对提示词进行版本管理

将提示词作为字符串存储在配置文件或小型提示词库中，按名称和版本索引。当某个变体通过微调产生更好输出时，记录该变更。这正是让提示词能在交付时从 nano-banana 迁移到 nano-banana-pro 而不出意外的原因。

负面约束很重要

如果某个提示词持续产生文字、标识或不想要的对象，将它们明确加入约束块。在各变体之间，清晰的负面约束往往比巧妙的措辞更可靠。

在 HiAPI 上构建可用的请求

每个变体都通过同一个 HiAPI 端点调用。请求有四个可变部分：基础 URL、认证头、模型字段和负载。

请求的形式

一个最小的图像生成调用如下所示：

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",
    "prompt": "Subject: a ceramic coffee mug on a wooden desk, steam rising\nStyle: soft natural light, editorial photography\nComposition: centered, negative space at top\nConstraints: no text, no logos",
    "n": 1
  }'

将 API 密钥保存在环境变量或密钥管理器中——绝不放在源码中。model 字段是切换变体时唯一需要更改的内容，prompt 字段承载上一节中的四块结构。

在 Python 中，同样的调用只需要几行：

import os, requests

def generate(prompt, model="nano-banana-2"):
    resp = requests.post(
        "https://api.hiapi.ai/v1/images/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": model, "prompt": prompt, "n": 1},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()

响应包含什么

响应携带图像结果——通常是一个 URL 或编码负载——以及标识处理该请求的模型的元数据。将模型字段读回并记录：这是事后判断哪个变体生成了给定资产的最廉价方式。

交付前确认参数

可选参数的确切集合因变体而异，并会随时间演变。在将 model 和 prompt 之外的任何内容硬编码之前，请查看实时模型文档以获取当前字段名和可接受值。将任何未记录的内容视为不受支持，而不是猜测。

处理响应、失败和重试

图像生成是一次背后有模型的网络调用，因此要为失败的部分做好规划。

先验证再信任

每次响应后，检查三件事：HTTP 状态、是否存在图像负载，以及返回的模型是否与你请求的一致。任何不匹配都要显式失败，而不是将坏资产传递到下游。

只重试值得重试的失败

并非每个错误都值得重试。格式错误的提示词或无效的模型名称每次都会以同样方式失败——应修复请求。超时、连接重置和速率限制响应等瞬时失败值得重试。

使用带抖动的有界指数退避：

import time, random

def call_with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except (TimeoutError, ConnectionError):
            if attempt == retries - 1:
                raise
            time.sleep((2 ** attempt) + random.random())

限制总尝试次数，这样损坏的请求就不会无限循环，并记录每次尝试的模型和提示词哈希，以便看出某个特定变体是否不稳定。

有意识地回退

如果某个变体持续失败，回退到家族中的另一个成员可以让流水线保持存活。因为三者共享请求形式，回退只是在重试时使用不同的 model 值。提前决定顺序——例如，当高保真调用反复失败时，从 nano-banana-pro 回退到 nano-banana-2——并记录回退何时触发，以便你注意到模式。

让失败可见

在存储返回的负载之前先验证它，并对重试和回退发出指标。当错误率攀升时，你希望在一批任务静默产生空白之前就知道。

交付前的加固

在将图像生成呈现给用户之前，请过一遍这份清单。

确认 ID 和参数

模型标识符会变化。重新核对 Nano Banana 家族当前的模型名称，并对照实时文档确认每个可选参数。不要交付只存在于旧示例中的值。

集中配置

将模型 ID、提示词模板和重试限制放在一个配置模块中。当你将提示词从 nano-banana 升级到 nano-banana-pro 时，这应该是一次配置变更，而不是分散在多个文件中的代码变更。

记录重要信息

对于每次调用，记录模型、提示词版本、响应状态、延迟，以及是否发生了重试或回退。对长提示词进行哈希，使日志保持可读。这正是能够回答“为什么这张图昨天看起来不一样？”的原因。

扩展时监控用量

由于计费跟随用量，请关注调用次数和变体组合。每个请求都悄悄升级到 nano-banana-pro 可能会把探索工具变成成本问题。有意识地路由：迭代用廉价变体，最终输出用更强变体。

测试端点

编写一个小型冒烟测试，用固定提示词对每个变体各调用一次，并断言响应有效。每次发布前针对当前文档运行它，这样模型变更就永远不会在生产环境中让你措手不及。

以单一客户端、共享提示词库和有意识的路由策略交付，HiAPI 上的 Nano Banana 家族就会成为你从草稿扩展到最终渲染而无需重写集成的唯一依赖。

查看全部文章 →