开发者从图像生成 API 中需要什么

开发者不需要一个让人觉得“充满魔法”的图像生成 API。他们需要的是它“按预期工作”。

在合适的地方，最好的 API 应该是“无聊”的：它接收清晰的输入，返回清晰的状态，让失败变得容易理解，并且不会迫使团队围绕供应商粗糙的边角再构建一个“第二产品”。

任务状态应当明确

图像生成可能需要时间。有些任务很快完成，有些会排队，还有些会因为模型或输入不正确而失败。

这意味着 API 应当清晰地暴露任务状态：

• accepted
• queued
• running
• completed
• failed

这些状态让开发者能够构建真实可信的用户界面，而不是通过超时来猜测发生了什么。

错误应当贴近问题

含糊的错误会浪费时间。如果输入太大，就说明这一点。如果模型不可用，就说明这一点。如果生成工作器失败，就应该明确指出，而不是返回一个通用的“错误请求”。

好的错误信息不需要暴露私有内容。它们需要指出失败的具体操作。

流式进度会更好

轮询可以工作，但进度流会让图像生成流程的体验好得多。用户可以看到任务仍在运行，应用也能在输出到达时做出相应反应。

这对生成是更大流程一部分的产品尤其重要：编辑器、仪表盘、资产管道以及内部工具。

API 应当尊重数据

开发者还需要知道提示词和源图像会去哪里。如果 API 将内容发送给第三方提供商，或将其存储用于训练，这些都不应被隐藏在细则里。

只有当 API 背后的集成足够私密时，集成才真正“足够私密”。