AI 图片生成 API：TypeScript 调用示例

AI 图片生成 API 通过一次程序化任务把提示词转成图片。在 Pipe2 中，先启动 Image Generator，再轮询返回的任务 ID，最后从已完成任务的资源中读取图片 URL。下面的 TypeScript 示例使用当前目录中成本最低的有效模型与质量组合。

使用 TypeScript SDK 生成图片

安装 @pipe2-ai/sdk，把 Pipe2 个人访问令牌写入运行环境的 PIPE2_TOKEN，然后使用 Node 运行该模块。示例提示词只定义一个主体、一个场景和一种光线，便于判断首次输出是否符合预期。

import { createClient } from '@pipe2-ai/sdk';

const input = {
  model: 'gpt-image-2',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.',
  quality: 'fast',
};
const client = createClient(process.env.PIPE2_TOKEN);
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

while (true) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (run?.status === 'completed') {
    console.log(run.assets?.[0]?.url);
    break;
  }
  if (run?.status === 'failed') throw new Error(run.error_message ?? 'Image generation failed');
  await new Promise((resolve) => setTimeout(resolve, 3000));
}

程序中的管道请求与以下 JSON 完全一致：

{
  "pipeline_slug": "image-generator",
  "input": {
    "model": "gpt-image-2",
    "prompt": "A small red paper boat on a rain-darkened stone step, soft morning light, editorial product photograph, no text.",
    "quality": "fast"
  }
}

TypeScript SDK 文档介绍了安装、身份验证、管道操作、资源上传、订阅和额度查询。

理解启动、轮询与资源获取流程

RunPipeline 接收管道 slug 和一个 JSON 输入对象。它不会一直保持连接直至图片完成，而是返回异步任务的标识符。请保存 run_pipeline.run_id；GetPipelineRun 通过它读取最新状态。

轮询代码处理两种终止状态。completed 任务可能包含生成的资源，示例会输出第一个资源的 URL。failed 任务可能带有 error_message，应与任务 ID 一同记录。生产代码还应设置总超时时间，并在找不到任务时直接报错。需要实时更新时，SDK 还提供异步可迭代的 WatchPipelineRun。

从成本最低的有效请求开始

示例固定使用 gpt-image-2 和 quality: 'fast'。在当前 Image Generator 目录中，这是成本最低的有效组合，对应模型的低质量生成档。它适合先验证身份验证、请求结构、轮询和资源处理，再为最终图片使用更高成本的设置。

fast 是成本选择，并不保证首张图片已达到发布质量。在批量生成前，用相同的 pipeline_slug 和 input 调用 EstimatePipelineCost。只要改变模型、质量或参考图片数量，就应重新估算；实际扣费以当前有效目录为准。

只选择图片真正需要的控制项

文本提示词本身即可运行。Image Generator 还可接收参考图片、一段受支持的参考视频、宽高比、质量、模型和提示词增强偏好。不同模型的限制并不相同，因此应读取管道 schema，而不是假设所有引擎都支持同样的媒体。

仅凭文本生成时，用简短连贯的句子写清主体、构图、光线和风格。需要在图片中逐字呈现的文字应放在引号内，并在生成后校对。使用参考图片时，要说明每张图片的用途以及必须保持的细节。五种通用宽高比是 1:1、16:9、9:16、4:3 和 3:4。

使用 Auto 可让 Pipe2 选择兼容引擎。只有当产品依赖某项已记录的模型能力，或需要进行受控比较时，才应固定模型。AI 图片生成器对比说明了如何保持提示词、参考素材、画幅和尝试次数一致。

安全处理令牌、失败与输出 URL

创建 SDK 客户端时，从运行环境中读取 Pipe2 令牌。不要把令牌写进源码、提交到仓库或暴露在浏览器日志中。请求指定的是 Pipe2 管道 slug，客户端无需再发送模型供应商的单独密钥。

轮询前先保存任务 ID，这样进程重启后仍可继续追踪同一任务。把返回的资源 URL 当作应用数据：若需要长期引用就持久保存，读取数组第零项前先确认资源存在，并将错误明确返回，而不是无限重试。对于用户提交的提示词或参考媒体，也要执行应用自身的授权、审核和保留策略。