Nano Banana API 指南：在 TokenLab 上进行图像生成与编辑

Nano Banana API 在 TokenLab 上有三个定价模型 ID，其中最便宜的模型每张图像的成本大约是中间档模型的一半。昂贵的错误通常不在于模型选择，而在于将编辑请求发送到了错误的端点，或者重复提交了已经创建任务的请求。本指南涵盖了确切的 ID、可用的文本生成图像调用、参考图像调用、异步轮询、预期错误以及费用设置方式。价格和字段列表读取于 2026 年 10 月 3 日，请在发布前再次确认。

关键要点

• 发送确切的 ID：nano-banana-2、nano-banana-2-lite 或 nano-banana-pro。显示名称并非请求别名。
• Nano Banana 的参考图像工作流应发送至 POST /v1/images/generations，并包含 operation: "image-to-image" 和 image_urls。不要发送至 /v1/images/edits 或 /v1/chat/completions。
• 我们在 2026 年 10 月 3 日读取的基础价格分别为 lite、标准和 pro ID 的每张图像 $0.0168、$0.0335 和 $0.067。每个模型都有一个价格区间，请在 Usage 中确认确切的层级。
• 如果创建响应包含 task_id、status: "pending" 或 poll_url，则意味着你必须轮询 GET /v1/tasks/{id}，直到状态变为 completed 或 failed。
• 即使任务失败，状态读取也会返回 HTTP 200。请根据任务的 status 字段进行分支处理，而不是根据 HTTP 代码。
• 最终费用记录在 Usage 和 billing_transaction_id 中，而不是复制的价格表中。

Nano Banana API 模型、定价单位及用途

当我们对比本指南的早期草稿与当前文档时，发现了三个问题：它列出的模型没有价格；它通过聊天补全发送了 Nano Banana 编辑请求；它使用了一个图像指南中未使用的过滤器查询目录。下表修正了第一个问题，后续章节修正了后两个问题。

模型 ID	最佳用途	定价单位	TokenLab 价格 (USD)	来源，观察结果
nano-banana-2	文本生成图像和图像生成图像，支持 aspect_ratio 和 resolution (1k, 2k, 4k)。发布于 2026-02-26。	per_image	每次请求 $0.0335。区间 $0.0225 至 $0.0755。	实时模型 API, 2026-10-03
nano-banana-2-lite	最便宜的文本生成图像和图像生成图像。我们看到的价格条目涵盖了 1k 层级。	per_image	每次请求 $0.0168。最低和最高均为 $0.0168。	实时模型 API, 2026-10-03
nano-banana-pro	文本生成图像、图像生成图像以及支持 aspect_ratio 和 resolution 的图像编辑。	per_image	每次请求 $0.067。区间 $0.067 至 $0.12。	实时模型 API, 2026-10-03
nano-banana	仅支持 aspect_ratio 的文本生成图像。无公开的 resolution 选择。	无证据	查看模型页面或定价端点	目录, 2026-10-02; 创建图像文档, 2026-10-03

以上所有价格均带有 is_lock_price: true，并于 2026-10-02T16:53:30.068Z 更新。在选择模型前，有三个细节需要注意：

• 分辨率层级会影响价格。 实时 API 显示 nano-banana-2 和 nano-banana-pro 有一个价格区间，但我们的证据并未将每个层级映射到具体分辨率。不要假设 1k 就是基础价格。请阅读你所选模型的定价条目。
• 文本输出有其独立的 token 价格。 nano-banana-2 和 nano-banana-pro 都有 native-gemini-text-output 条目。当 outputModality 为 text 时适用。对于 nano-banana-2，输入为 0.25，输出为 1.5。对于 nano-banana-pro，输入为 1，输出为 6。单位为 per_token。在进行预算规划前，请在 GET /v1/models/:model/pricing 中确认规模。
• Lite 模型未列出可接受的请求格式。 nano-banana-2-lite 的实时记录显示为“未列出”。在基于它进行开发前，请先阅读其详细信息。

为了进行粗略预算，我们将基础价格乘以数量。以下是基于基础价格的估算，而非报价：

• 在 nano-banana-2-lite 上生成 100 张图像：100 × $0.0168 = $1.68。
• 在 nano-banana-2 上生成 100 张图像：100 × $0.0335 = $3.35。
• 在 nano-banana-pro 上生成 100 张图像：100 × $0.067 = $6.70。

更高分辨率的层级会增加这些数字。

若要自行列出当前的图像模型，请调用图像生成指南中使用的端点。之前的草稿使用了 category=image，但该指南并未记录此参数。

curl "https://api.tokenlab.sh/v1/models?recommended_for=image" \
  -H "Authorization: Bearer sk-your-api-key"

有关单个模型的操作、价格和生命周期，请使用获取模型 (Get a Model)。你也可以浏览 TokenLab 模型目录。

使用 Nano Banana API 发送文本生成图像请求

在 TokenLab 仪表板中创建 API 密钥并导出：

export TOKENLAB_API_KEY="your-tokenlab-api-key"

务必发送 model 参数。创建图像参考文档指出图像 API 不会选择默认模型。缺少模型参数会返回 400 错误，并显示 param: "model"。

此请求仅使用文档中为 Google 图像系列列出的字段。我们将 resolution 保持为 1k，因为 nano-banana-2 文档中包含 1k、2k 和 4k。

curl -X POST "https://api.tokenlab.sh/v1/images/generations" \
  --max-time 120 \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "A minimalist ceramic vase on a natural wooden table, studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "response_format": "url"
  }'

--max-time 120 标志符合文档要求。文档称高分辨率请求可能需要近一分钟或更长时间，因此请将客户端超时设置为至少 120 秒。文档提到 size 是 Google 图像系列的兼容性别名，但建议直接使用 aspect_ratio。

同步成功会直接返回生成的图像。以下占位符仅展示文档规定的格式：

{
  "created": 1700000000,
  "data": [
    { "url": "https://example.com/generated-image.png" }
  ]
}

请按以下顺序读取：

1. 如果响应体包含 task_id、status: "pending" 或 poll_url，则你得到的是一个任务，而非图像。请跳转至轮询部分。
2. 否则，读取 data[0].url。如果使用 response_format: "b64_json"，则读取 data[0].b64_json。
3. created 是 Unix 时间戳。revised_prompt 仅在模型返回时出现，因此不要强制要求它。
4. 存储图像 URL、你自己的作业 ID、模型以及响应头中的 request_id。

生成的图像 URL 可能作为媒体副本保留 30 天。请检查每个项目的 media_retention.items 以获取其状态和 expires_at。挂起或失败的副本不保证保留，因此如果需要长期保存，请将文件复制到你自己的存储空间。数据保留指南中有详细说明。

使用参考 URL 编辑图像

假设目录团队希望在干净的摄影棚背景下拍摄同一产品。诱人的做法是使用 /v1/images/edits，但文档排除了这种做法。Nano Banana 参考图像请求通过 /v1/images/generations 暴露，并使用 operation: "image-to-image"。/v1/images/edits 并非它们的正确路径。

此请求来自图像生成指南，使用 nano-banana-2 作为模型：

curl https://api.tokenlab.sh/v1/images/generations \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana-2",
    "operation": "image-to-image",
    "prompt": "Keep the product shape, change the background to a bright studio setup",
    "image_urls": ["https://example.com/input/product.png"],
    "aspect_ratio": "1:1"
  }'

我们遵循以下规则：

• 发送文档规定的参考字段。 在 JSON 中使用 image_url、image_urls 或 reference_image_urls。不要发送顶层的 images[] 或 file_id。这些属于编辑流程，在此端点会被拒绝。
• 使用公共 URL。 它们必须是 http 或 https，不包含嵌入式凭据、片段或私有网络主机。避免使用在处理开始前可能过期的签名 URL。
• 对私有源使用 multipart。 文档为私有或受标头保护的源提供了 multipart image 文件上传方式。
• 将 resolution 与模型匹配。 文档称 nano-banana-pro 可能包含它，而 nano-banana-edit 应省略它。文档还将 nano-banana-edit 命名为参考图像模型，但该 ID 不在我们 2026-10-02 获取的目录中。在使用任何 ID 前，请先通过 /v1/models 进行验证。

原始文章中的聊天补全编辑示例已移除。实时记录将 gemini_generate_content 列为 nano-banana-2 和 nano-banana-pro 可接受的格式。我们的证据并未记录聊天补全图像编辑路径。

基于掩码的修复 (inpainting) 和诸如 strength 之类的参数在我们的证据中未针对 Nano Banana 进行记录。在发送它们之前，请检查 GET /v1/models/{model}。

图像请求何时变为任务以及如何轮询

图像创建调用要么是同步的，要么是异步的，响应会告诉你结果。异步作业指南列出了触发字段：task_id、status: "pending" 或 poll_url。如果出现其中任何一个，data[] 数组将为空，且工作仍在进行中。

我们的证据仅针对 gpt-image-2 和官方 FLUX/BFL 图像模型记录了 async: true 请求标志。它并未针对 Nano Banana ID 进行记录。不要将其添加到 Nano Banana 请求中。如果返回任务响应，请处理它；如果需要异步行为，请检查模型详细信息。

想象一下，浏览器刷新在响应缓慢后重新发送了创建调用。你现在需要为两次生成付费。文档称大多数重复生成都源于这种重试。请遵循以下顺序：

1. 立即保存 ID。 存储 id 或 task_id、poll_url、模型、端点以及你自己的作业 ID。id 和 task_id 是相同的值。
2. 轮询 URL。 有 poll_url 时使用它。否则调用固定路由：

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

1. 每 5–10 秒轮询一次。 指南称这对于长媒体作业通常足够。
2. 了解状态。 状态包括 pending、processing、completed 和 failed。已取消的任务显示为 failed，并带有 cancelled: true。
3. 在终端状态停止。 在 completed 时，读取 data[].url。异步图像结果仅为 URL，绝非 b64_json。在 failed 时，读取 error 和 error_details。
4. 安全处理超时。 如果创建调用在看到响应前超时，请检查 request_id 并查找任务，然后再重试。如果你存储了任务 ID，请恢复轮询。如果状态轮询失败，请使用退避机制重试该轮询，不要重新创建。

即使对于失败的任务，状态读取也会返回 HTTP 200。失败的任务可能包含 error_details，其中包含 status、type、code、message、param 和 retryable。例如，error_details.status: 400 且 param: "size" 意味着请求需要更正。这并不意味着轮询本身失败。重试失败的生成会创建一个新任务，并可能产生新的费用。

预期的错误及处理方法

通过 HTTP 状态和 code 处理错误，绝不要通过 message 处理。错误处理指南指出消息可能会在不通知的情况下更改。聊天补全和响应使用 OpenAI 风格的 error 对象，而 Gemini 和 Anthropic 格式保持其各自的形状。不要在所有 TokenLab API 之间共享同一个解析器。

状态 / 代码	可能原因	处理方法
400, param: "model"	未明确模型	发送 model。使用 /v1/models?recommended_for=image 列出 ID。
400 不支持的字段，或 unsupported_parameter	模型未记录的字段，例如在不支持的模型上使用 resolution	移除该字段或切换模型。不要重复发送未更改的请求。
400 参考图像错误	端点错误，或 URL 私有/过期	使用 /v1/images/generations 和 image_urls。使用公共、稳定的 URL。
401 invalid_api_key 或 expired_api_key	密钥缺失、撤销或过期	更换密钥。
402 insufficient_balance 或 quota_exceeded	余额不足，或密钥达到自身限额	充值、提高密钥限额或选择价格较低的模型。
403 model_not_allowed	密钥无法使用该模型	更新密钥的模型列表。
404 model_not_found	未知或不可用的 ID	阅读 /v1/models 并使用当前 ID。
413 payload_too_large	请求或文件过大	减小输入。
429 rate_limit_exceeded	窗口内请求过多	等待 Retry-After，然后重试。
500–504, all_channels_failed	服务或供应问题	仅在 retryable 为 true 时重试。尊重 retry_after 并限制尝试次数。

503 all_channels_failed 并不总是意味着中断。如果 retryable 为 false 且缺少 retry_after，则所选交付层级中没有供应。重复请求无济于事，因此请先检查 GET /v1/models。

任务轮询有其自身的失败情况：

• 404 async_task_not_found：任务已过期或不存在。检查保存的 task_id 和 poll_url。
• 403 task_not_owned：任务属于另一个工作区。检查 API 密钥属于哪个工作区。
• 已完成但没有媒体 URL 的任务：视为失败。保留 ID 并联系支持团队。

联系支持团队时，请发送 request_id、task_id、billing_transaction_id（如果存在）、端点、模型、时间和字段名称。切勿发送密钥、私有媒体或签名 URL。

图像请求的费用是如何确定的

所有三个定价的 Nano Banana ID 都使用 per_image 单位，因此主要费用是模型的 per_request 价格。计费指南补充了相关规则：

• 一个结果，一次收费。 每个已完成的请求都会被收费一次，按产生结果的交付选项计费。TokenLab Verified 使用 TokenLab 公共价格。Official 使用官方价格层级。Auto 先尝试 Verified，然后是 Official。
• 层级设定最终数字。 实时价格区间（nano-banana-2 为 $0.0225 至 $0.0755，nano-banana-pro 为 $0.067 至 $0.12）表明单一固定价格并不涵盖所有请求。分辨率层级可能是驱动因素，请在模型的定价条目中确认。
• 任务优先预留。 异步任务在被接受时可能会预留其估计成本。已完成的任务收费一次，失败的任务会释放或退还挂起金额。计费指南称失败的任务不收费。
• 破折号不代表免费。 在模型页面上，TokenLab 价格列中的破折号表示目前没有 Verified 报价。

要确认费用，请使用以下途径：

1. GET /v1/models/:model/pricing 或 Pricing API 获取当前价格。
2. 控制台，在确认付费生成前显示最大估算值。
3. Usage 查看按模型计算的最终费用。
4. 响应或任务中的 billing_transaction_id，以及 X-Billing-Transaction-ID 标头。流式传输和某些原生格式可能仅在标头中暴露它。

如果 Usage 在任务完成后未显示最终费用或释放金额，请将请求 ID 和任务 ID 发送至 support@tokenlab.sh。不要将本文中的价格复制到你的代码中。计费指南建议在你的应用程序需要显示或比较成本时读取当前价格。

常见问题解答

图像生成图像请求应该发送哪个 Nano Banana 模型 ID？

实时记录列出了 nano-banana-2、nano-banana-2-lite 和 nano-banana-pro 的 image-to-image 功能。文档还提到了 nano-banana-edit，但它不在我们 2026-10-02 获取的目录中。请使用 operation: "image-to-image" 和 image_urls 将 ID 发送到 /v1/images/generations。请在你自己的图像上进行小规模测试，因为我们的证据中没有质量对比。

为什么我的图像请求返回了 task_id 而不是图像？

创建调用作为异步任务运行。在响应中查找 task_id、status: "pending" 或 poll_url。保存这些字段，然后每 5–10 秒轮询一次 poll_url 或 GET /v1/tasks/{id}，直到状态为 completed 或 failed。在等待期间不要发送第二个创建请求。

我可以从 Nano Banana 模型获得 base64 输出吗？

response_format 字段接受 url 或 b64_json，同步请求可以返回 data[].b64_json。异步图像结果仅为 URL，无论你要求什么格式。检查所选模型的详细信息以确认它是否接受 b64_json，因为字段因模型而异。

失败的图像任务会收费吗？

计费指南称失败的任务不收费，任何挂起的预留都会被释放或退还。重试失败的生成会创建一个新任务，并可能产生新的费用。请使用 billing_transaction_id 和 task_id 在 Usage 中确认结果。

在 TokenLab 仪表板中创建一个密钥，使用 nano-banana-2-lite 发送上述文本生成图像请求，并在 Usage 中检查费用。