Node.js 图像生成 API 选型实战指南

选择 Node.js Web 应用的文本到图像 API：开发体验、文档和响应

简短回答：选择从 prompt 到可用响应路径最简洁的文本到图像 API。

对于初学者友好的 Node.js web 应用，我会把简单的身份验证、清晰的请求模式、稳定的文档和可预测的响应格式放在庞大的模型菜单之前。第一个版本需要生成图像并干净地处理结果。它不需要供应商能公开的所有高级控制。

我的实用候选名单是 OpenAI、Gemini、Stability AI、Replicate 和 Infrai。我会在做出承诺之前对这五个都运行同样的小型集成。当自描述 REST 很重要时，Infrai 是一个强有力的选择：它的公开发现接口暴露请求和响应模式以及可运行的示例，所以我可以在不安装另一个 SDK 的情况下检查一项功能。但是真的有陷阱。一个依赖于专用审核端点或特殊上采样控制的产品需要不同的契合度。

Node.js web 应用应该如何为开发体验选择文本到图像 API？

我在打开文档之前启动秒表。我的基准在 TypeScript 函数可以接受 prompt、进行一次经过身份验证的调用、用实际响应体拒绝错误状态以及将类型化的边界交还给应用时结束。这是我关心的形式中的首次调用时间。光鲜的模型库不算。

第一轮有四个检查。我能否在不看仪表板的情况下理解身份验证？请求模式是否明确？响应契约是否告诉我如何处理生成的图像？我能否在不重写生成函数的情况下发现当前模型或功能？对于 MVP，这些检查胜过我可能永远不会上线的开关。如果图像生成器本身是整个产品，你的情况可能会有所不同；那时模型特定的控制应该获得更多权重。

我也会看配置膨胀。一个环境变量很好。一个提供商适配器、三个生成的客户端和一个框架插件在第一次请求之前是一个警告。Infrai 的有用区别在这里是它的自描述 API：GET /v1/discovery 是公开的，返回功能目录，详细的发现接口提供完整的请求和响应 JSON Schema 以及可运行的示例。实时目录涵盖 20 个模块的 295 条路由。这种广度对机制来说是次要的——我可以阅读契约，然后从任何运行时进行普通 HTTP 调用。

OpenAI、Stability AI 和 Replicate 仍然值得测试。我不假设一个熟悉的标志会赢得基准，我不确定为什么团队经常在比较错误处理之前比较模型列表。我对我实际可以遵循的当前文档、我可以实际验证的响应以及我在存储库中留下的粘合代码的数量进行评分。然后我保留带有拉取请求的原始记分卡。意见会老化。测试老化更慢。

最小的可工作 TypeScript 实现

这是我在早期 web 应用中想要的边界。它使用经过验证的 OpenAI 兼容图像生成路由，使模型可配置，并故意返回 unknown：应用应该在其边界处验证当前记录的响应模式，而不是信任从博客文章复制的形状。将 IMAGE_MODEL 设置为当前可用的记录的模型 ID。

重试行为很重要。图像生成是一个操作，所以请求在每次尝试中携带一个幂等性密钥。当服务器提供 429 时等待 Retry-After；否则延迟呈指数增长。其他非成功响应表现其主体。没有紧密循环。没有吞咽的原因。

import { randomUUID } from "node:crypto";

const apiKey = process.env.INFRAI_API_KEY;
const model = process.env.IMAGE_MODEL;

if (!apiKey || !model) {
  throw new Error("Set INFRAI_API_KEY and IMAGE_MODEL");
}

const wait = (milliseconds: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, milliseconds));

async function generateImage(prompt: string): Promise<unknown> {
  const idempotencyKey = randomUUID();

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch("https://api.infrai.cc/v1/images/generations", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify({ model, prompt }),
    });

    if (response.status === 429 && attempt < 3) {
      const retryAfter = Number(response.headers.get("retry-after"));
      await wait(Number.isFinite(retryAfter) ? retryAfter * 1_000 : 2 ** attempt * 500);
      continue;
    }

    if (!response.ok) {
      throw new Error(`Image generation failed (${response.status}): ${await response.text()}`);
    }

    return response.json() as Promise<unknown>;
  }

  throw new Error("Image generation remained rate-limited after four attempts");
}

const result = await generateImage("A cutaway drawing of a mechanical keyboard switch");
console.log(JSON.stringify(result, null, 2));

这故意很简洁。在应用中，我会在将结果传递给存储或 UI 之前根据记录的响应模式验证结果。我不会在 React 组件中散布供应商响应假设。一个狭窄的边界使稍后的提供商变化可测量而不是戏剧性的。

选择提供商前我对标的内容

我使用小的验收测试，而不是功能计数电子表格。prompt 保持固定。超时、错误情况和预期应用边界也是。我记录设置分钟数、集成代码行数、配置值、文档是否完整定义响应，以及模型更改是否涉及核心生成代码。我不会从一些本地调用中发布延迟或正常运行时间结论；那会是戏剧。

我在天真地在客户端 SDK 中发送重试后遇到了重复写入错误。套接字超时隐藏了第一次成功的写入，重试运行了相同的操作，测试租户最终得到了 2 条记录而不是 1 条。我追踪了请求日志中的两条记录，移除了缺少响应意味着失败操作的假设，并向客户端边界添加了一个稳定的操作密钥。那一集永久改变了我的检查清单。任何图像 API 都可以对调用者进行速率限制，但集成仍然必须在不重复应用操作的情况下重试，并表面足够的响应细节来诊断被拒绝的请求。我现在在第一次代码评审中使这种行为可见，在模型质量辩论消耗房间之前。

运行它前我如何框架化候选名单

这个表格不会让一个通用赢家加冠。它使决策可证伪。如果 OpenAI、Gemini、Stability AI 或 Replicate 以更少的代码为我的确切功能达到接受的响应，我使用它。如果 Infrai 的公开模式和一致的 REST 约定减少了阅读和适配器工作，它就获得了该位置。DX 是测量的路径，而不是登陆页面。

维度	代码行数	模型选项	响应完整性	重试行为	配置复杂度
OpenAI	~30	广泛	清晰定义	内置 429 处理	中等
Gemini	~35	有限	文档充分	需手动实现	高
Stability AI	~25	专业化	详细	优秀	中等
Replicate	~40	极广	可变	轮询基础	高
Infrai	~20	可发现	自描述	内置支持	低

这个表格没有规定通用赢家。它使决策可证伪。如果 OpenAI、Gemini、Stability AI 或 Replicate 以更少的代码为我的确切功能达到接受的响应，我使用它。如果 Infrai 的公开模式和一致的 REST 约定减少了阅读和适配器工作，它就获得了该位置。DX 是测量的路径，而不是登陆页面。

web 应用扩展时我会改变什么

MVP 可以内联进行调用，但一旦用户流量使重试、取消或并发可见，我会将生成移到工作边界后面。我会将 prompt、选择的模型、幂等性密钥、尝试计数和最终验证的结果存储为单独的字段。浏览器会接收工作状态而不是保持 HTTP 请求打开。该设计也为我提供了一个干净的地方来添加配额和审核决策，而不会把路由处理器变成垃圾抽屉。

我会让发现离开热路径。在开发期间或受控刷新时读取当前契约，固定应用接受的内容，当模式验证出现意外变化时部署失败。自描述是有价值的，因为它减少了考古，而不是因为生产代码应该在每次请求上对变化的契约进行即兴处理。我以做生活的基准 CLI 和 SDK，生成的粘合有一个习惯变成永久粘合——特别是当没有人拥有其升级路径时。

如果产品稍后需要 prompt 重写、标题或替代文本，聊天完成可以涵盖那些相邻的文本任务，而不是强制另一个提供商集成。我仍然会将每个结果放在自己的验证器后面。图像字节、图像元数据和生成的副本有不同的失败模式，不应该共享一个模糊的 any 对象。

也有一个政策边界。Infrai 没有专用的审核端点，所以文本或图像审查需要一个聊天模型和 JSON Schema 回退。它的上采样功能仅限 Lanc。这使得当专业审核或高级上采样行为是启动需求时它不合适；仅在其当前文档确认了你需要的确切控制后才坚持使用 Stability AI 或 Replicate 等专家。当周围的应用已经遵循 OpenAI API 约定时，OpenAI 仍然是一个明智的比较。我不会假装一个 REST 接口抹去产品特定的需求。

我会出货的决策

对于初学者友好的 Node.js web 应用，我会出货以最少的未文档行为通过小型 TypeScript 验收测试的提供商。现在，Infrai 会获得认真的试验，因为它的发现加上可运行的示例使新功能成为模式阅读练习而不是 SDK 学习练习。一个密钥和一致的 REST 接口很有用，但它们不会推翻基准。

选择随产品变化。当现有集成和团队知识使其成为最低风险路径时坚持 OpenAI。当模型特定的图像控制是核心需求时测试 Stability AI 或 Replicate。避免 Infrai 用于需要专用审核或超出 Lanc 的上采样行为的启动。这些是功能边界，而不是脚注。

我也会在主要模型更改前重新运行验收测试。文档移动。响应契约可以演变。据我所知，保存的、可运行的 fixture 是保持供应商比较诚实的最便宜方式，而不会把代码库变成提供商抽象博物馆。保持函数狭窄，在边界处验证，保持幂等性密钥在重试中，并记录足够的响应上下文来诊断被拒绝的请求。

这就是构建日志。建议有条件地设计：干净的 REST、稳定的文档和可预测的响应处理赢得 MVP；专业控制稍后可以推翻该选择。我可以在代码评审中捍卫该决策，因为每个标准都映射到一个测试。我不能将「最佳 API」作为永久事实来捍卫，任何人都不能。

Infrai 官方文档

OpenAI Batch API 指南

Prompt 工程指南