图像生成 API：团队实用指南

图像生成 API：团队实用指南

图像生成 API 在演示中很容易测试，在生产环境中却出乎意料地容易被误用。一个团队可以发送一个 prompt，得到一张好看的图片，但对于后续真正重要的问题仍然没有答案：哪个模型应该负责哪类工作负载，请求被拦截时会发生什么，如何在上线前估算成本，以及产品、设计和工程如何审核输出，而不把每一张图都变成一次人工例外处理？

本指南面向正在评估图像生成 API 用于产品界面、广告、电商创意、agent 工作流或内部内容运营的团队。它提供一个实用工作流，帮助你在承诺某个提供商、某个模型或某种集成方式之前，先把流程理清。

Flatkey 在你的团队希望使用一个 API 密钥、一个共享余额、一份用量账本，以及一个用于文本、图像、视频和工具调用的路由器时，能够很好地适配这套工作流。你仍然可以选择适合任务的模型。运营层面的差异在于，你的团队可以在一个地方审查支出、延迟和用量，而不是分别追逐不同的提供商账户。

快速答案

选择图像生成 API 时，应根据工作负载与审核流程进行匹配：

错误做法是根据样例画廊是否好看来选择图像生成 API。更好的决策方式是先定义工作流，选择 API 接口形态，设定审核指标，然后再测试模型。

图像生成 API 实际上必须完成什么

对于生产团队来说，图像生成 API 不只是“输入 prompt，输出图片”。它必须支持一个可重复的运营循环：

1. 接受来自用户、工作流或 agent 的结构化创意输入。
2. 将请求路由到合适的图像模型或提供商。
3. 以所需的宽高比、文件类型、质量级别和分辨率返回图片。
4. 处理被拦截的 prompt、格式错误的输入、提供商错误和超时。
5. 保留足够的请求上下文，用于审核、调试和成本报告。
6. 让团队在不每次都重写应用的情况下比较模型。

这就是为什么团队应该将图像生成 API 视为基础设施，而不是新奇功能。生产级集成必须能够承受提示词修订、品牌规范、审核行为以及财务方面的问题。

先从用例开始，而不是从模型开始

在比较模型之前，请先写下工作流程需要创建的确切图像类型。像“生成营销图片”这样模糊的目标还不够。一个有用的用例应包含输入、约束、审核标准以及回退路径。

请使用此模板：

这个练习可以防止一种常见失败模式：团队选中了一个令人印象深刻的模型，随后才发现它无法可靠地处理实际的审核流程。

选择合适的 API 形态

大多数团队需要的不止一种图像生成 API 模式。OpenAI 现有的图像生成文档将图像生成分为用于直接生成和编辑的 Image API，以及用于对话式或多步骤流程中的图像生成的 Responses API。Google 的 Gemini 图像生成文档将 Nano Banana 描述为 Gemini 的原生图像生成功能，支持在文本、图像、视频和混合输入之间进行对话式生成和编辑。

这种区分很重要。如果你的产品只需要根据提示词生成单张图片，那么直接的图像端点会更简单。如果你的工作流程需要迭代编辑、上传参考素材，或者需要一个在多轮中不断修订视觉内容的代理，那么对话式或多模态工作流可能更适合。

请使用此决策表：

最适合你团队的图像生成 API 可能是多种方案的组合：用直接端点处理简单工作，用多模态路由处理编辑，再加上一层网关用于模型切换、使用情况审查和团队控制。

团队的生产工作流

以下是我建议在上线前采用的实用运行工作流。

1. 定义三个黄金提示词

选择三个代表真实工作的提示词：

• 简单提示词： 系统应快速且低成本完成的内容。
• 品牌提示词： 带有语气、风格、产品或布局约束的真实提示词。
• 困难提示词： 带有参考图、文本渲染、严格宽高比或多步骤指令的提示词。

不要只针对一个漂亮的演示提示词做优化。一个有用的图像生成 API 测试集应该能揭示模型何时速度快、何时符合要求，以及何时需要人工审核。

2. 固化输出要求

在接入 API 之前先写好输出契约：

• 宽高比或精确尺寸。
• 文件格式。
• 质量等级。
• 背景要求。
• 是否允许透明背景。
• 输出中是否可以包含可读文本。
• 请求是否可以包含参考图像。
• 可接受的最大延迟。
• 每张可接受图像的最高成本。

当你尝试新模型时，这个输出契约就会成为你的回归测试标准。

3. 将提示词失败与系统失败分开

图像生成 API 可能因为请求在技术上无效、提供商不可用、账户触发限流、提示词被拦截，或者生成的图像未达到你自己的审核标准而失败。请将这些视为不同的失败类别。

这种分类很重要，因为盲目重试会浪费预算。例如，OpenAI 的图像文档建议像处理其他 API 错误一样处理图像生成失败，记录请求 ID，并重试暂时性故障，而不是用户可修正的提示词错误。若要进行更深入的度量，可将此工作流与图像生成 API 指标结合使用。

4. 尽早加入人工审核队列

即使你的长期目标是自动化，也应先从审核队列开始。存储提示词、模型、输出图像、失败类别、请求 ID（如果有）、成本、延迟、审核者决定以及拒绝原因。

对于最初的 100 到 300 个真实输出，你的目标不是完全自动化。你的目标是了解哪些提示词、模型、尺寸和审核标准与被接受的图像相关。

5. 决定何时路由或升级

并非每张图像都应使用同一个模型。你的路由策略可以很简单：

• 草稿和内部缩略图使用最快、最低成本的模型。
• 最终品牌素材、复杂产品场景或包含文本的图像使用更强的模型。
• 当用户提供参考图像时，使用具备编辑能力的模型。
• 当请求依赖外部上下文时，使用具备更强 grounding 或多模态支持的模型。
• 当素材面向客户、受监管、对品牌敏感或重跑成本高时，升级到人工审核。

Flatkey 在这里很有用，因为应用可以保持稳定的集成接口，而团队可以切换图像模型，并从同一账本中审查使用情况。

示例：通过 Flatkey 调用兼容 OpenAI 的图像路由

Flatkey 的 API 快速入门支持将 OpenAI SDK 指向 https://router.flatkey.ai/v1，并使用你的 FLATKEY_API_KEY。对于通过兼容 OpenAI 的接口公开的直接图像生成路由，请保持应用契约尽量小，并记录结果。

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: "https://router.flatkey.ai/v1",
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: [
    "为 B2B SaaS 上线创建一张 16:9 的主视觉图片。",
    "风格：干净的技术编辑风。",
    "避免出现过小且无法辨认的 UI 文本。",
    "为标题预留安全的留白空间。"
  ].join(" "),
  size: "1536x864",
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync("hero.png", Buffer.from(imageBase64, "base64"));

在上线之前，请加入生产控制：

• 在调用图像生成 API 之前，先验证请求的尺寸和格式。
• 保存提示词版本、模型、路由、请求 ID、延迟和成本。
• 添加一个人工拒绝原因字段。
• 将被阻止的提示词与瞬时错误区别处理。
• 将最终资产通过与人工创建图片相同的素材管道发送。

示例：使用原生 Gemini 图像路由

某些图像工作流更适合通过原生多模态路由来处理。Google 的 Gemini 文档描述了 gemini-3.1-flash-image 以及相关的 Nano Banana 模型，用于图像生成和编辑，包括文本加图像到图像的工作流。对于电商特定的创意操作，请参阅相关指南 面向电商创意流程的 AI 图像生成 API。

具体载荷取决于你的网关和模型路由，但其操作思路是一致的：

{
  "model": "gemini-3.1-flash-image",
  "input": [
    {
      "type": "text",
      "text": "为一只哑光黑色陶瓷马克杯在混凝土桌面上创建一个方形产品场景。保留马克杯的形状，并在左上角留出干净空间。"
    },
    {
      "type": "image",
      "mime_type": "image/png",
      "data": "<BASE64_REFERENCE_IMAGE>"
    }
  ],
  "response_format": {
    "type": "image",
    "image_size": "1K"
  }
}

当图像生成 API 需要理解参考图、保留某个对象，或修改现有视觉内容时，请使用这种风格。关键的审查指标不是“它看起来酷不酷？”。指标是模型是否在保留不应改变的细节的同时，完成了要求的修改。

首月需要衡量什么

如果你只跟踪总支出和总图片数，就会错过真正的运营成本。应改为跟踪被接受的输出。

Flatkey 的使用日志在这一阶段尤其有用，因为同一个团队可以在请求之后查看模型、token 数量、延迟和成本。对于图像生成 API 工作，请将你自己的接受/拒绝决策数据与这些基础设施日志并排记录。如果你的团队正在标准化的不止是图像路由，统一 AI API 指南展示了如何保持更广泛的基础 URL 和 SDK 迁移整洁。

无需猜测的成本规划

图像生成定价会因模型、质量级别、分辨率、输出格式以及请求是否包含图像输入而异。不要只按最低标称的单张图片价格来比较 API。

使用这个上线估算公式：

每月被接受资产数量
× 每个被接受资产的平均生成次数
× 每次生成的平均提供商或网关成本
+ 编辑/参考图像开销
+ 存储和 CDN 成本
+ 审核人工成本
= 预计每月图像工作流成本

例如，一个每月需要 1,000 张被接受图像、且每张被接受图像平均需要 2.4 次生成的工作流，在编辑、存储和审核时间之前，实际上就是一个 2,400 次生成的工作负载。这才是你的图像生成 API 评估应当优化的数字。

Flatkey 的实时模型目录是你在进行上线估算前查看当前可用图像模型和单图价格的正确位置。请在决策时使用定价页面和模型目录，而不是把静态数字复制到规划文档中。

安全与治理检查清单

团队通常会用一把共享密钥测试图像生成 API。对于一次快速验证来说这没问题，但对生产环境而言却很薄弱。在上线前，请落实以下控制措施：

• 为开发、预发布、生产和代理分别使用独立密钥或子密钥。
• 为实验和非生产工作流设置预算上限。
• 限制每个环境可以调用的模型。
• 记录提示词元数据，但不要不必要地存储敏感客户数据。
• 根据你的数据保留政策保存上传的参考图像。
• 将生成的资产存入你的常规资产系统，而不只是 API 响应中。
• 审查面向客户图像的许可、品牌、隐私和审核要求。
• 为高流量任务添加紧急关闭开关。

如果你的团队已经在使用 Flatkey 处理文本、视频或工具调用，那么图像生成也可以共享同样的治理模式：一个余额、模型白名单、使用日志，以及财务可见的请求历史。

内部评估计分卡

使用计分卡，而不是围绕主观质量进行漫长争论。

至少在两条模型路由和三类提示词上运行计分卡。最终胜出者应该是能够稳定产出通过审核资产的路由，而不是那个单次样本最惊艳的路由。

何时网关会有帮助

当一个团队使用一个图像模型处理一个稳定工作流时，直接接入供应商就已经足够。只有当图像生成 API 成为更广泛操作系统的一部分时，网关才开始变得重要：

• 产品希望在应用内生成时使用一个模型，而增长团队希望广告使用另一个模型。
• 代理需要来自同一余额的图像、文本、浏览器和补充工具。
• 财务希望有一张账单以及按请求级别的使用可见性。
• 工程希望在不替换 SDK 代码的情况下评估新模型。
• 运营需要预算、模型白名单和按密钥归属。
• 因为创意任务与上线日期绑定，所以可靠性很重要。

Flatkey 就是为这种多模型、多工具的操作层而构建的。实际收益不是让每个图像请求都自动路由。收益在于，你的团队可以把模型选择变成一项运营策略，而不是硬编码依赖。

实施清单

在选择或上线图像生成 API 之前，请确保每一项都有负责人：

• 代表简单、品牌敏感和困难工作流的三个黄金提示词。
• 涵盖尺寸、格式、质量、背景和参考输入的输出契约。
• 适用于草稿、最终版、编辑和高上下文图像任务的模型候选清单。
• 错误分类法，包括无效请求、临时性提供商问题、配额/速率限制、安全拦截和审核失败。
• 避免对提示词或策略错误进行盲目重试的重试策略。
• 包含提示词、模型、输出、决策、原因、延迟和成本的审核队列。
• 基于已接受资产而非原始生成次数的成本估算。
• 面向环境、团队和代理的关键策略。
• 前 30 天的使用日志复核频率。
• 提示词模板和品牌规则的内部负责人。

常见问题

什么是图像生成 API？

图像生成 API 是一种程序接口，允许应用通过文本提示词、图像输入或两者结合来生成或编辑图像。在生产环境中，该 API 还需要错误处理、成本跟踪、安全行为、审核元数据和资产存储。

适合团队的最佳图像生成 API 是什么？

最佳图像生成 API 取决于工作流。直接图像端点通常最适合单提示词生成，最简单直接。多模态或对话式路径更适合图像编辑、参考图像和迭代式工作流。当团队需要多个模型、统一账本、共享治理以及更轻松的模型切换时，网关会更有帮助。

团队应如何比较图像生成 API 工具？

应根据已接受图像成本、提示词遵从度、编辑成功率、延迟、安全拒绝率、重试行为、治理控制和集成工作量来比较工具。不要只根据样张图库质量或单张图片标价来比较。

OpenAI 兼容 API 适用于图像生成吗？

如果网关或提供商通过 OpenAI 兼容的图像路径暴露图像模型，它就可以适用。对于更复杂的多模态图像工作流，原生提供商路径可能暴露出通用兼容层无法完全覆盖的能力。上线前请同时测试端点契约和模型行为。

Flatkey 如何帮助进行图像生成 API 运维？

Flatkey 为团队提供一个密钥、一个共享余额、一个模型目录、在支持时提供 OpenAI 兼容路由，以及用于复核的使用日志。这让团队更容易评估图像模型、控制支出，并将图像生成 API 的使用与文本、视频和代理工具调用放在同一运营层上。

下一步

如果你正在评估图像生成 API，请先从上面的工作流模板和评分卡开始。然后用你正在考虑的模型运行三个黄金提示词，并比较已接受图像成本、延迟、审核时间和失败类别。

使用 Flatkey，你可以通过一个账户测试图像模型，在一个地方复核使用情况，并让应用代码专注于工作流，而不是提供商碎片化。