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 图片生成器对比说明了如何保持提示词、参考素材、画幅和尝试次数一致。

通过 Image Generator 调用 Nano Banana Pro API

要通过 Pipe2 API 使用 Nano Banana Pro，请沿用 image-generator 管道，并将 input.model 设为 gemini-3-pro-image。Nano Banana Pro 是模型在目录中的名称；请求中应使用 Pipe2 的模型标识符。SDK 方法、任务 ID、轮询循环和返回的图片资源都遵循上面的流程。身份验证使用 Pipe2 令牌。

比较输出时，保留示例提示词，只更换模型。现有的 GPT Image 2 fast 请求适合以较低成本检查集成；运行 Nano Banana Pro 前，请用 EstimatePipelineCost 估算修改后的请求。对于该模型，quality: 'fast' 选择 1K 输出，auto 或 hd 选择 2K。两种尺寸采用同一价格档，因此 fast 不会像 GPT Image 2 那样降低价格。该管道不提供 Nano Banana Pro 的 4K 输出。

文本提示词即可运行，也可提供最多 14 张 reference_images。请在提示词中说明每张参考图的作用。不要向该模型发送 reference_videos：Image Generator 中的 Nano Banana Pro 不支持视频输入。如果希望不带参考图的请求原样使用你的提示词，请将 enhance_prompt 设为 false。需要明确的版式时，应描述每个元素的位置，用引号标出需要逐字呈现的文字，并在使用前检查生成图片。

通过 Pipe2 调用 GPT Image 2 API

上面的示例已经配置好通过 Pipe2 API 使用 GPT Image 2：发送 pipeline_slug: 'image-generator'、input.model: 'gpt-image-2' 和文本提示词，并使用 Pipe2 令牌进行身份验证。保存返回的任务 ID，用相同的 SDK 方法轮询状态，在任务完成后取得图片资源。选择该模型不会改变这一流程。

集成示例中的 quality: 'fast' 对应低质量档，auto 对应中质量档，hd 对应高质量档。这些是 Pipe2 的输入值，请按原样发送，不要替换成质量档的名称。提高质量前，先估算修改后请求的费用。在此管道中，GPT Image 2 最多接受五张 reference_images，不支持 reference_videos。添加参考图片时，请说明每张图片的作用，并检查输出是否有意外变化，尤其是文字和产品细节。

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

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

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