新我们如何抓出挂错模型的卖家,并在发生时为你退款。
UberLLM

如何选择和集成图像生成 API

比较图像生成 API 的功能、请求字段、异步结果、模型测试、错误处理和计费,并提供生产集成步骤。

超过 15 亿张图片 已通过文本到图像算法生成,截至 2023, 月,自 DALL-E 2 发布以来,平均每天生成约 34 万张,根据 Everypixel 的 AI 图像统计分析。同一分析指出,其中约 12.6 亿张,大约占 80%,归因于基于 Stable Diffusion 的模型、服务和应用程序。

达到这个量级,图像生成就不再是创意演示,而变成了基础设施。决定产品能否发布的问题,不再是哪个模型能画出更漂亮的图片,而是关于请求契约、任务状态、超时行为,以及失败的生成是否仍然会出现在你的账单上。

这是一份针对 图像生成 API 层的开发者指南。它涵盖了请求如何构建、任务如何经历生命周期、如何测试模型而不是盲目相信排行榜,以及成本隐藏在哪里。每张图片的成本是最容易比较的数字,但它本身却最不实用。

目录

图像生成 API 功能一览

功能 输入 输出 检索模式
文本生成 消息和参数 流式文本 流式响应
文本到图像 提示词、尺寸、模型标识符 一张或多张图像 任务,轮询或 webhook
图像编辑 源图像、指令、可选的蒙版(如果支持) 编辑后的图像 任务,轮询或 webhook
文本到视频 提示词、时长、分辨率 视频文件 任务,轮询或 webhook
图像到视频 源图像、提示词、时长 视频文件 任务,轮询或 webhook
音乐生成 提示词、风格、时长 音频文件 任务,轮询或 webhook
语音合成 文本、语音 音频文件 流式音频或返回的文件

一个 endpoint 和一个 API key 可以同时覆盖多个模型系列,因为模型标识符是选择系列和版本的关键。这种便利性也伴随着一些挑战。每个系列接受不同的参数集,因此适用于一个模型的请求体可能在另一个模型上失败,并且它们之间的尺寸、蒙版、种子支持和多输出限制都各不相同。

图像生成 API 是一种托管推理服务,包含三个部分:将提示词和设置转换为签名调用的请求契约、承载图像及其元数据的结果对象,以及用于处理超出单个 HTTP 响应生命周期的作业生命周期。每个部分都需要有自己的设计决策,并且每个部分的失败方式也不同。

这种模式比看起来要年轻。Stable Diffusion 于 2022年8月22日 公开发布,确立了大多数提供商仍在使用的服务模式,正如 TechCrunch 在发布时报道 的那样:应用程序发布提示词和参数,提供商运行 GPU 工作,然后返回图像或任务。该模型可以在高端消费级硬件上运行,并在几秒钟内生成 512×512 像素的图像,它是在 LAION-5B 上训练的,LAION-5B 是一个包含大约 5.85 亿图像-文本对的数据集,其中包含一个经过美学过滤的子集,大约有 600 百万对。Stability AI 声称,在早期公测期间,超过 15,000 名测试人员每天生成约 2 百万张图像,这是最明确的早期信号,表明托管访问而非桌面软件是需求的形式。

接下来的章节将按照实际集成中遇到问题的顺序进行:首先是请求字段和响应对象,然后是异步任务状态、模型选择测试、编辑保真度和来源、延迟和重试、分步集成、计费单位,以及最后的测试调用。将生成功能集成到自动化管道中的团队通常希望完整地演示一次整个流程,而这个 用于自动化工作流的图像 API 演练 展示了从触发到存储资产的完整周期。

请求模式和响应字段

大多数首次集成都会在请求体中出现问题,很少是因为提示词。按照字段在网络传输中的顺序构建它们,调试时间就会缩短。

  • 模型标识符。 在您自己的思考中首先发送它,因为它决定了其余字段是否合法。一个模型接受的负面提示词或遮罩,下一个模型可能会拒绝。
  • 提示词和负面提示词。 负面提示词在某些系列中是受支持的字段,而在其他系列中则被忽略,因此请验证而不是假设。
  • 尺寸或宽高比。 以模型期望的方式表达它,可以是像素或命名比例。在推理之前在本地验证它,因为一个被拒绝的调用会花费一次往返时间,而一个后期失败的生成会花费一次超时和一个队列槽位。
  • 输出数量。 每次调用多个输出看起来很高效,直到您注意到计费通常是按数量而不是按调用次数来计算的。
  • 输出格式。 PNG、JPEG 或 WebP 格式对您的下游转换工作的影响与字节数一样大。
  • 种子。 每当可复现性很重要时,请包含它。没有它,“再运行一次”意味着“再掷一次骰子”。
  • Webhook URL。 长时间运行的任务在您的请求返回后完成,并且回调比紧密的轮询循环更经济。
  • 幂等性键。 生成是昂贵的,因此,没有键的重试创建会变成第二个计费任务和一张重复的图片。

先验证再消费。 首先在您自己的代码中检查宽高比、模型标识符和必填字段。本地模式检查可以捕获那些否则会在队列等待后以 400 形式出现的错误类别,并且它能完全阻止格式错误的流量进入按量计费的 endpoint。

响应端是团队丢失已付费资产的地方。OpenAI 的图像 API 参考 展示了大多数提供商趋同的结构,一个包含 base64 payload、托管 URL 以及(如果支持)修订提示词的图像对象。将提供商返回的任何内容规范化为您自己的稳定模式,并保留一个原始提供商元数据块,以用于您的模式尚未建模的控制项。

字段 内容 生产注意事项
资产 URL 指向生成文件的链接 生命周期短且受访问控制,因此请在过期前下载
b64_json base64 编码的图像字节 适用于小型同步响应,但对于大型 payload 会占用大量内存
revised_prompt 模型改写后的提示词 存储它,因为它能解释您意料之外的输出
模型标识符 生成此输出的模型和版本 审计和复现所需
尺寸和格式 宽度、高度和 MIME 类型 与请求的宽高比进行确认
校验和 文件的完整性哈希 下载后和任何格式转换后进行验证

将 base64 视为传输细节,而非存储策略。 编码后的图像会使 payload 大约膨胀三分之一,并在您的应用程序解析 JSON 时占用内存。对于生产环境的媒体文件,请将解码后的字节写入对象存储,并向您的前端提供一个带签名的检索 URL。在存储时,将 MIME 类型和校验和添加到记录中,这样损坏的下载就会被您的管道捕获,而不是由用户发现。

我在代码审查中会强制执行的规则是: 每个存储的资产在其元数据中都包含模型标识符、种子、有效提示词和请求时间戳。没有这四项,关于“上个月一张奇怪的图片”的支持工单将无法得到解答。

当模型版本在您不知情的情况下发生变化并导致输出漂移时,这个习惯会第一次带来回报。存储的元数据将模糊的投诉转化为您可以运行的比较。

异步作业、任务状态和结果检索

图像和视频作业不会在聊天完成中返回。创建一个作业,保留其标识符,然后观察其状态变化。

一个流程图,说明了图像生成API系统的异步作业工作流程。

创建调用会返回一个任务标识符,您的应用程序应将其写入与包含提示和模型的请求记录中。此后,作业会报告五种状态之一,每种状态都要求您的代码执行不同的操作。

状态 含义 应用程序操作
queued 已接受并等待容量 保留任务ID并按计划轮询
running 生成进行中 等待,并根据模态设置超时
succeeded 输出已就绪 立即下载并存储资产
failed 生成未完成 在任何重试之前读取错误类别
expired 输出不再可检索 重新生成,不要将其视为结果丢失

已过期状态常常让团队感到困惑,因为它看起来像是他们自己系统中的一个错误。但事实并非如此。提供商会在有限的时间窗口内保留结果文件,而且这个窗口很短。在UberLLM上,图像链接大约会保持有效15分钟,视频和音乐结果文件在作业完成后大约会保留3小时。一个每十分钟检查一次并在下一个部署周期才采取行动的轮询循环将完全错过图像链接。

检索通过两种机制运行,成熟的系统会同时使用这两种机制。轮询可以弥补webhook丢失的交付,当您的服务无法暴露公共端点时,它是唯一的选择。Webhook通过准确告知您状态何时改变来减少浪费的请求,这在作业需要一分钟而不是一秒钟时尤为重要。webhook和轮询之间的权衡归结为故障处理:当您的接收器宕机时,webhook会失败,当您的轮询间隔过短时,轮询失败的代价很高。

轮询间隔应遵循模态,而非代码库。一个适用于4秒图像作业的单一固定循环,会在运行一分钟或更长时间的视频作业上浪费数十次调用。

文本响应会逐个token流回,而图像和视频作业则会交给您一个需要轮询的任务,或者由webhook报告为就绪。这种差异是架构性的,而非表面上的:即时返回的请求仍然拥有尚未完成的工作,并且必须有人记住它。记录状态转换时间以及最终状态,因为排队中和运行中之间的间隔是容量问题在影响用户之前显现的地方。

模型选择标准及测试方法

公开排名对模型的评分基于你的产品中永远不会发送的提示词。它们衡量的是你无法控制条件下的样本质量,对延迟尾部、拒绝一致性或不同构建版本之间输出的漂移情况只字不提。一个基于你自己的图像类别构建的测试集,在一个下午就能告诉你比排行榜一个月所能提供的信息更多,而且它能经受住下一次模型发布。

评估必须是可衡量的行为,而不是凭感觉判断。正式的评估程序对待图像生成的方式,就像负载测试对待吞吐量一样:有明确的协议、固定的输入和评分的输出,而不是评审员的印象。生产环境的 API 应该在每次调用时记录相同的可复现维度:提示词类别、模型和版本、可用的种子、分辨率、延迟、故障模式和安全结果。记录每次请求的延迟,以便延迟尾部保持可见,因为健康的平均值可能会掩盖那些长时间挂起并触发超时的工作。

标准 衡量方法 通过信号
提示词依从性 对每个类别的固定提示词集进行评分审查 所需对象、数量和颜色出现在大多数输出中
感知质量 团队进行盲测对比审查 评审员在不知道哪个模型生成的情况下选择输出
文本渲染 需要精确单词或标签的提示词 大多数样本中的单词拼写正确
身份一致性 在多次生成中保持同一主体 面部、产品或角色保持可识别
拒绝行为 应该被拒绝的提示词 拒绝行为一致且归入明确类别
可复现性 使用相同的种子和模型版本重复调用 当种子和版本匹配时,输出保持接近

单独对每一行进行评分。 一个聚合数字会掩盖一个完美渲染产品标签但拒绝所有包含儿童的提示词的模型,或者一个生成精美肖像但文本像验证码的模型。造成损害的失败总是特定于类别的,将其平均成一个单一分数是它在不被注意的情况下进入生产环境的方式。

路由会增加模型测试无法捕捉到的治理问题。当市场或故障转移层更换提供商时,替代者必须提供同等的审核保证,否则结果必须明确标记为具有不同的保障特性。静默放松安全检查是最糟糕的故障转移行为:没有错误,但输出只是在较弱的审查下到达。将审核决策和模型版本保留在审计记录中,并公开你的应用程序可以根据其进行分支的错误类别。

实际可行的样本量: 每个类别几十个提示词用于初次测试,并将精确的提示词和输出保存到代码库中。每当模型版本字符串更改时,就重新运行整个测试集,而不是等到有人抱怨时才运行。

最后一点是团队经常跳过的。模型标识符可以指向一个新的构建,而你这边无需做任何更改,因此测试集不是发布工件,而是一个在每个发布周期都运行的回归测试套件。当结果提交给工程部门以外的利益相关者时,一个关于单个模型功能的通俗易懂的演示,由 ImagesArt AI 解释,可以在评分辩论开始前为对话提供一个共同的基线。

发布前检查编辑忠实度和来源信息

一个看起来不错的编辑不一定是一个成功的编辑。编辑需要进行两次评分:一次是看请求的更改是否发生,另一次是看其他所有内容是否保持不变。如果仅凭第一次评分就发布,你可能会得到一张模特重绘了标志的产品照片。

研究支持这种区分。HQ-Edit 论文]将对齐度 (Alignment) 和连贯性 (Coherence) 作为独立的指标引入,并报告称,在一个评估系统中,微调将对齐度提高了 12.3 分,将连贯性提高了 5.64 分。两个数字独立变化是整个论点的关键:一个输出可能遵循了指令,但却破坏了你需要保留的部分;或者它可能保留了所有内容,但却忽略了指令。

我会在发布前运行的验收测试:

  1. 选择 20 到 30 张原始图片,这些图片应包含人脸、印刷文本、标志和复杂的背景。仅使用裁剪过的产品照片,可能会让一个在人脸处理上表现不佳的模型通过测试。
  2. 为每张图片编写一条指令,并在同一行记录预期的更改。模糊的指令会导致对结果的争论,而非发现问题。
  3. 遮盖编辑区域,并将其余部分与原始图片进行差异比较。遮盖区域之外的像素是你的保留分数,而数字差异比较可以解决肉眼无法判断的问题。
  4. 在单独的列中对对齐度 (alignment) 和保留度 (preservation) 进行评分,然后查看它们不一致的情况。这些情况表明提示词需要重新措辞,或者模型需要更换。
  5. 将每个输出都进行大小调整和格式转换,然后确认水印或内容凭证是否保留。在你的 CDN 管道中丢失的来源信息,就如同你从未拥有过。
  6. 确认提供商的内容政策以及任何披露义务,这些政策和义务适用于你发布产品的市场。政策因提供商而异,一个路由过的请求可能会受到不同政策的约束。
  7. 记录保管链,从源文件到交付的资产,包括处理它的模型版本。

第五步是团队后期才发现的问题。凭证和隐形水印是关于来源的证据,而不是所描绘事件真实性的证明。可靠性取决于受信任的身份、签名过程以及每个下游步骤是否保留了 metadata,因此大小调整、裁剪和重新编码都需要检查。来源信号可以提高可追溯性,但它不能确立事实的真实性或确认权利已获许可。

对于任何正在构建编辑功能的人来说,一个令人不安的结论是:来源 metadata 回答的是“这来自哪里”,它永远无法回答“这个说法准确吗”或“我们有许可吗”。这些仍然是法律和编辑方面的问题。

如果编辑界面是产品本身,那么区域保留应被视为一个硬性门槛,而非一个质量分数。图片编辑 API 指南]是关于 endpoint 和 parameter 方面的一个有用参考,而这份 AskYourQA AI 测试指南]有助于构建评分体系,从而避免对齐度 (alignment) 和保留度 (preservation) 混为一谈。

生产环境中的延迟、错误和重试行为

大多数图像API比较都只关注每张图像的价格和样本质量,然后就止步了。延迟尾部、故障率和恢复行为才是决定你的功能是否感觉“坏掉”的关键指标,而这些指标却无人公布。一项图像生成基准测试明确指出,延迟和观察到的正常运行时间将留待未来阶段进行,而一项独立测试发现,提供商通常不公布实际延迟数据,因此不得不自行测量响应时间、错误率、冷启动和吞吐量,正如API基准测试图像生成分析]所记录的那样。

测量百分位数,而不是平均值。分别跟踪同步和异步图像调用的p50,、p95和p99,然后加上超时率、冷启动惩罚、从创建到可检索结果的时间,以及成功输出率。单一的平均值会掩盖用户体验到的“尾部”情况,即大多数请求在两秒内完成,而少数请求却需要四十秒。

时间上的意外通常与模态有关。在我们对2026年10月29日的测试中,一个5秒的Kling 3.0视频片段生成大约花费了80秒。这并没有错;视频生成需要数分钟,而图像生成只需数秒,如果将图像路径的超时设置直接复制过来,可能会取消正常进行的任务。

症状 可能原因 解决方案
任务在超时后仍处于运行状态 提供商缓慢或不可用 取消,然后使用相同的幂等键重试,或在可用时重新路由
网络超时后出现重复图像 未使用幂等键重试创建调用 每次创建请求都发送一个幂等键
突发请求期间出现429响应 达到速率限制 采用带抖动的指数退避并排队请求
503响应 提供商或路由暂时不可用 稍后带上限重试,仅在安全保障有效时才进行故障转移
402响应 余额或支付检查失败 充值余额,然后重新发送相同的请求
404响应 模型标识符或路由未找到 根据当前目录检查标识符
图像链接无法加载 签名URL已过期 成功后下载并存储文件到你自己的存储中

只重试可重试的请求。429或503是瞬时错误,值得采用带抖动的指数退避和硬上限。402或404将永远以相同方式失败,因此请先修复余额或模型标识符。我们的API会拒绝带有402,、404,、429和503,的调用,类别是信号,而不仅仅是HTTP状态。

关于成本的逆向解读: 最便宜的每图像API在生产环境中往往是最昂贵的。重试、失败的生成和不可预测的尾部延迟会将工作推回到你的应用程序中,并将用户推出你的漏斗。

根据同一基准分析,可靠性已成为一个采购标准,在37%的组织中,其重要性仅次于成本优化(58%)、模型可用性(49%)和速度(41%)。市场权衡是真实存在的:跨提供商路由可以减少中断,但也会增加排队时间、区域性能和安全过滤器延迟的差异。每个重新路由的请求都应作为其自身的路由进行测量,并拥有自己的百分位数,否则聚合仪表板将隐藏正是失败的路径。

如何一步步集成图像 API

生产环境的集成是一系列简短的决策,其中大部分是关于记录而非请求。以下是经受住真实流量考验的集成顺序。

一个五步图表,说明了将图像生成 API 集成到应用程序中的工作流程。

  1. 为每个环境创建范围受限、可撤销的密钥。 独立的密钥意味着泄露的测试环境凭证可以在不影响生产流量的情况下被撤销。
  2. 将现有客户端指向新的 base URL。 OpenAI 兼容的 base 是 UberLLM OpenAI 兼容的 base URL,并且由于平台同时接受 OpenAI 和 Anthropic 的 wire formats,因此一旦 base URL 和凭证更改,现有客户端即可工作。在切换之前,请确认您依赖的图像 endpoint 是否受支持。
  3. 从当前目录中将模型标识符完整地复制为字符串。 这样,切换模型时只需更改一个值,这是一行差异而不是重构。提供商原生的 ID 也以同样的方式工作,例如 fal-ai/kling-video/v3/standard/text-to-video。
  4. 在本地验证尺寸和宽高比,附加一个 idempotency key,然后发送 create call。 这些廉价的检查应该在您的网络侧完成。
  5. 将任务标识符与请求记录一起存储,然后进行 poll 或注册 webhook。 如果进程在 create 和 store 之间中断,您将为无人能找到的输出付费。
  6. 成功后,下载 asset,验证 checksum 并将其保存到您自己的存储中。 等待直到下一个用户请求才获取文件,是导致过期链接变成支持工单的原因。
  7. 为每个 job 记录模型标识符、状态、持续时间和错误类别。 这四个字段可以在没有 debugging session 的情况下回答大多数生产问题。
  8. 在上线前演练失败路径,包括 429,、请求超时和过期链接。未经测试的重试代码通常会使重复图像的数量翻倍,而不是减少它。

一个简短的演练比首次构建的字段列表更有价值,尤其是在检索方面:

一个成功的集成最终会是这样:每个 job 都有一个状态,每个成功的 job 在您的 bucket 中都有一个 asset,并且每个 asset 旁边都有一个已记录的模型版本。这就是全部标准。这也是三月份令人印象深刻的演示与十一月份您仍然可以调试的功能之间的区别。

计费单位以及如何比较实际成本

两个 API 都可能声称“按图片计费”,但实际计费方式却可能不同,因为计费单位、尺寸依赖性和失败策略都会改变计算方式。首先比较计费单位,然后计算每个可用输出的成本。

模式 常用计费单位 需检查事项
文本生成 输入和输出 token 输入和输出单独计费
图像生成 按图片或按百万像素 模型和输出尺寸会改变单位成本
图像编辑 按编辑次数或按输出图片 源图像是否会产生额外费用
视频生成 按片段或按秒(取决于提供商) 生成完成后按最终价格计费
音乐和语音 按音轨、按分钟或按字符 每个模型实际使用的单位
失败任务 按尝试次数收费,或完全不收费 失败的生成是否会出现在账单上

按百万像素计费的方式会惩罚大尺寸输出,而按图片计费则不会。 一个在 1024×1024 看起来很便宜的模型,在打印分辨率下成本可能会高出数倍,因此请以您的产品实际渲染的尺寸进行比较,而不是以营销截图中的尺寸进行比较。

视频需要在预测中单独列项。一个在生成完成后按最终价格计费的片段比一个在运行时计费的片段更容易预测,因为您预测的是完成的输出,而不是实际运行时间的不确定性。编辑是隐蔽的一项:检查源图像是否作为输入收费,因为每次调用都发送一个 4 MB 源图像的修图工作流程,可能会使单位成本远超广告宣传的编辑价格。

失败的生成是最终决定两个供应商之间选择的关键项。假设有 1,000 个图像任务,失败率为 5%。如果失败任务被计费,您需要支付 1,000 个任务的费用才能获得 950 张可用图像,这比标价显示的每张可用图像多出大约 5%。如果失败任务不计费,您只需支付 950。相同的标价,不同的实际价格。

我用于月度估算的公式: 预期用量 × 单位价格 × 重试系数,再加上编辑和视频的缓冲。重试系数是区分预测和愿望的数字。

然后,根据您自己的验收测试而不是供应商的示例图库来比较单位价格。如果您想在一个地方了解 token、图像和片段定价的底层逻辑,这篇关于 AI 定价模型 的分析解释了每个单位是如何计量的。

在选择模型之前运行测试调用

测试调用不应只回答“这张图片看起来好吗?”。检查模型是否达到您的质量标准,它如何处理编辑,以及在预期负载下其响应表现如何。一张出色的样本图片无法告诉您 API 在生产环境中将如何表现。

选择一个文本到图像的候选模型,以及一个支持编辑的候选模型。在所有候选模型中保持提示集不变,以便您可以在相同的任务上比较输出。使用 UberLLM,您可以通过更改模型标识符来切换模型,同时保持 API key 和 endpoint 不变。

按顺序测试:首先,根据您的选择标准对输出进行评分;其次,如果您的功能编辑图像,则运行编辑验收测试;然后在预期并发下测量 p50 和 p95 延迟。最后计算每个可用输出的成本,包括重试。未达到质量标准的模型不需要进行负载测试。

将提示、输出和请求日志保存在您的存储库中。当您更改模型标识符或版本时,重新运行相同的集合并比较结果。对于编辑,检查结果是否保留了您的应用程序所需的源细节;一张视觉上看似合理的图像仍然可能改变身份或其他重要特征。

通过或不通过: 仅当模型在预期工作量下通过质量、编辑和负载测试时才推广它。在功能标志后发布,并保留第二个候选模型以备故障转移。如果失败,则使用相同的集合测试下一个候选模型。

价格是决策的一部分,但不应主导决策。UberLLM 将 Nano Banana 2 图像生成定价为每张图像 $0.015,而列表价格为每张图像 $0.10。对于视频测试,UberLLM 推荐 Kling 3.0 Standard 作为文本到视频或图像到视频的起点。图像和视频请求会返回一个任务,您可以通过轮询或 webhook 进行跟踪,因此请在测试中包含完成时间和结果检索时间。

UberLLM 通过与 OpenAI 和 Anthropic 兼容的接口提供文本、图像、视频、音乐和语音模型。使用其 playground 比较图像输出,然后通过您的应用程序的 API 客户端运行相同的测试提示。在选择模型之前,综合评估质量、编辑保真度、延迟和每个可用结果的成本。