Grok Imagine API: Generate an Image with the Pipe2 SDK

For Grok Imagine API access through Pipe2, run Image Generator with model: 'grok-imagine-image'. Submit a text prompt, poll the returned run ID, and retrieve the generated image asset. This guide uses Pipe2’s API and authentication; it does not demonstrate a direct xAI API request.

Select Grok explicitly

The pipeline slug is image-generator; the model identifier goes inside input. Use grok-imagine-image for the standard model or grok-imagine-image-quality for Grok Imagine Quality. Auto may choose another engine, so pin the model when Grok is a requirement.

The example uses the standard model, no reference images, and quality: 'fast': a lowest-cost valid Grok configuration for this workflow. Fast selects 1K output; auto and hd select 2K. Standard Grok currently has the same base image price for both sizes; fast is not a further price discount. Reference images add cost. Use EstimatePipelineCost with the same slug and input before dispatching a workload.

Run the SDK example

Install the package with npm install @pipe2-ai/sdk. Save the following as grok-image.mjs, set PIPE2_TOKEN to a Pipe2 personal access token in your environment, then run node grok-image.mjs. Your account needs sufficient credits. Keep the token on the server.

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}`);

The matching pipeline request is:

{
  "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
  }
}

See the TypeScript SDK documentation for the client used by this JavaScript module and the API reference for the public API.

Keep the run ID until the image is ready

RunPipeline returns a run ID, not the finished image. GetPipelineRun retrieves its status and assets. The example stops on failure or cancellation, checks that a completed run has an asset, and prints the first image URL. It bounds polling to 60 checks with three-second waits; that is an application choice, not a generation-time guarantee.

If polling times out, resume checking the same run ID rather than submitting a duplicate generation. Store that ID as soon as dispatch succeeds. For production, also handle network errors and retain the returned asset reference wherever your application needs it.

Add references only when the task needs them

A text prompt is sufficient. Both Grok image models support up to three JPEG or PNG reference_images, with a maximum of 20 MB per image. They do not accept reference_videos in this pipeline. The available aspect ratios are 1:1, 16:9, 9:16, 4:3, and 3:4; the example uses the default square frame.

enhance_prompt: false keeps a prompt-only request from being rewritten before generation. Describe the subject, setting, framing, and light, then inspect the output before use. For more deliberate compositions, consult the Grok Imagine prompt guide. When adding references, explain what each contributes and re-estimate the modified request.