Grok Imagine API：通过 Pipe2 SDK 生成图片

要通过 Pipe2 使用 Grok Imagine API，请运行 Image Generator，并设置 model: 'grok-imagine-image'。提交文本提示词，根据返回的运行 ID 轮询状态，再获取生成的图片。本指南使用 Pipe2 的 API 和身份验证方式，不演示直接向 xAI API 发送请求。

明确指定 Grok 模型

流水线标识为 image-generator，模型标识放在 input 内。标准模型使用 grok-imagine-image；Grok Imagine Quality 使用 grok-imagine-image-quality。Auto 可能选择其他引擎，因此在必须使用 Grok 时，应明确指定模型。

示例采用标准模型、不附带参考图片，并设置 quality: 'fast'。这是能够演示此工作流程的有效 Grok 配置中成本最低的一种。Fast 输出 1K 图片，auto 和 hd 输出 2K 图片。目前，标准 Grok 在这两种尺寸下的图片基础价格相同；fast 并没有额外的价格优惠。参考图片会增加费用。批量运行之前，请使用相同的流水线标识和输入调用 EstimatePipelineCost。

运行 SDK 示例

使用 npm install @pipe2-ai/sdk 安装软件包。将下方代码保存为 grok-image.mjs，在环境变量 PIPE2_TOKEN 中设置 Pipe2 个人访问令牌，然后运行 node grok-image.mjs。账户需要有足够的积分。令牌应保存在服务器端。

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

const token = process.env.PIPE2_TOKEN;
if (!token) throw new Error('Set PIPE2_TOKEN');
const client = createClient(token);
const input = {
  model: 'grok-imagine-image',
  prompt: 'A small red paper boat on a rain-darkened stone step, soft morning light, editorial photograph, no text.',
  quality: 'fast',
  enhance_prompt: false,
};
const { run_pipeline } = await client.RunPipeline({
  pipeline_slug: 'image-generator',
  input,
});

for (let attempt = 0; attempt < 60; attempt++) {
  const { pipeline_runs_by_pk: run } = await client.GetPipelineRun({
    id: run_pipeline.run_id,
  });
  if (!run) throw new Error('Run not found');
  if (run.status === 'failed' || run.status === 'cancelled') {
    throw new Error(run.error_message ?? run.status);
  }
  if (run.status === 'completed') {
    const url = run.assets?.[0]?.url;
    if (!url) throw new Error('Completed run has no image asset');
    console.log(url);
    process.exit(0);
  }
  await new Promise((resolve) => setTimeout(resolve, 3000));
}
throw new Error(`Polling timed out; resume with run ID ${run_pipeline.run_id}`);

对应的流水线请求如下：

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

此 JavaScript 模块使用的客户端见 TypeScript SDK 文档，公开 API 见 API 参考。

图片完成前保留运行 ID

RunPipeline 返回的是运行 ID，而不是完成的图片。GetPipelineRun 用于获取状态和输出文件。示例会在失败或取消时停止，确认已完成的任务包含文件，并输出第一张图片的 URL。轮询最多检查 60 次，每次等待三秒。这是应用层的设置，并不保证生成时间。

如果轮询超时，请继续查询同一个运行 ID，而不要重复提交生成请求。请求成功启动后，应立即保存 ID。在生产环境中，还要处理网络错误，并在应用需要的位置保存返回的文件引用。

只在需要时添加参考图片

仅提供文本提示词即可生成。两个 Grok 图片模型的 reference_images 都支持最多三张 JPEG 或 PNG 图片，每张上限为 20 MB。它们在此流水线中不接受 reference_videos。可选宽高比为 1:1、16:9、9:16、4:3 和 3:4；示例采用默认的正方形画幅。

enhance_prompt: false 可防止纯文本请求的提示词在生成前被改写。描述主体、环境、构图和光线，并在使用前检查结果。要更细致地控制构图，可参考 Grok Imagine 提示词指南。添加参考图片时，应说明每张图片的作用，并重新估算修改后的请求费用。