Add Imagine image and video jobs to a Batch API queue

The Batch API accepts Imagine generations, edits, and video extensions alongside chat/Responses. Create the batch and poll as in Run a Batch API job. Use a batch-enabled Imagine model from the model page — unsupported models reject the request. Signed image/video URLs in results expire after 1 hour; download promptly.

SDK: prepare then add

from xai_sdk import Client

client = Client()
batch = client.batch.create(batch_name="imagine_overnight")
batch_requests = []

batch_requests.append(client.image.prepare(
    prompt="A sleek laptop on a minimalist desk",
    model="grok-imagine-image-2.0",
    batch_request_id="img_001",
))

batch_requests.append(client.image.prepare(
    prompt="Add a rainbow in the background",
    model="grok-imagine-image-2.0",
    image_url="https://picsum.photos/800",
    batch_request_id="img_edit_001",
))

batch_requests.append(client.video.prepare(
    prompt="A product rotating on a turntable",
    model="grok-imagine-video-1.5",
    batch_request_id="vid_001",
))

batch_requests.append(client.video.prepare(
    prompt="Make it slow motion",
    model="grok-imagine-video",
    video_url="https://lorem.video/cat_360p_3s",
    batch_request_id="vid_edit_001",
))

batch_requests.append(client.video.prepare_extension(
    prompt="The camera pans to a sunset behind the mountains",
    model="grok-imagine-video",
    video_url="https://lorem.video/cat_360p_3s",
    duration=6,
    batch_request_id="vid_ext_001",
))

client.batch.add(batch_id=batch.batch_id, batch_requests=batch_requests)

REST body shapes

POST /v1/batches/{batch_id}/requests — each item needs a unique batch_request_id:

Kind	batch_request key	Notes
Image gen	image_generation	prompt, model
Image edit	image_edit	prompt, model, image: { url, type: "image_url" }
Video gen / edit	video_generation	Edit adds video: { url }
Video extend	video_extension	prompt, model, video, duration

Example image generation line:

{
  "batch_request_id": "img_001",
  "batch_request": {
    "image_generation": {
      "prompt": "A sleek laptop on a minimalist desk",
      "model": "grok-imagine-image-2.0"
    }
  }
}

JSONL file upload

Each line is custom_id, method (POST), url, and body. Mix endpoints in one file:

url	Use
/v1/images/generations	Image gen
/v1/images/edits	Image edit
/v1/videos/generations or /v1/videos	Video gen
/v1/videos/edits	Video edit
/v1/videos/extensions	Video extend

Upload the JSONL via the Files API, then create the batch with input_file_id. Caps: 200 MB / 50,000 requests. File-based batches are sealed — you cannot call AddBatchRequests afterward.

Read results

After num_pending hits 0 (or as rows finish), page GET /v1/batches/{batch_id}/results. Image rows expose image_response (.url, .base64, .usage, .model). Video rows expose video_response (.url, .duration, .usage, .model). Match rows with your batch_request_id.

Pitfalls

• Batch completion is best-effort (often within 24 hours), not a hard SLA.
• Client-side function tools in a batch return tool_calls for you to handle offline; multi-turn needs a new batch request with tool results included.
• Do not leave media URLs sitting — they expire in one hour.