API 实战配方

商品图生成

每个预期输出使用一个稳定的 requestId。将返回的 imageUrl 和商品记录一起保存；网络超时时重试同一个 request id，不要创建新的生成任务。

const request = {
  prompt: "干净的电商商品摄影图：哑光黑色水壶放在石材台座上，柔和棚拍光线，为标题留出空白",
  model: "nano-banana-fast",
  ratio: "1:1",
  style: "studio",
  requestId: `catalog-${productId}-hero-v1`,
};

const response = await fetch("https://nanobananafree.app/api/nano-banana/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.NANO_BANANA_API_KEY}`,
  },
  body: JSON.stringify(request),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
await saveProductHero(productId, result.imageUrl, result.requestId);

重试规则

409 表示同一请求仍在处理或已经失败，应先查看历史记录。
402 表示 credits reservation 失败，不要无限重试。
最多四个变体可以使用同步 batch API。部分项目失败时返回 HTTP 207，每个项目都有独立的 request id、扣费和退款记录。异步任务完成回调可以在登录后的 Webhooks 控制台创建，或调用 POST /api/webhooks。

const batch = await fetch("https://nanobananafree.app/api/nano-banana/batch", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.NANO_BANANA_API_KEY}`,
  },
  body: JSON.stringify({
    prompt: "干净摄影棚中的高级香蕉产品海报",
    model: "nano-banana-fast",
    count: 3,
    batchRequestId: "product-poster-v1",
  }),
});
const payload = await batch.json();
const successfulImages = payload.results.filter(
  (item) => item.status === "succeeded"
);

可复用生产设置

如果同一套提示词和设置会重复使用，可以在登录后的工作室保存一个命名工作流。它只保存生成上下文，不会把图片字节写入 workflow 记录。若需要长期保留生成图片，仍应在自己的资产系统中保存结果 URL 或文件。

商品图生成

重试规则

可复用生产设置

On this page