Images and Videos in Batches — Batch API: Bulk Processing

Updated November 2, 2026 based on xAI documentation: the batch discount is 20% on eligible text models (not 50%), examples follow the REST API and the official xai-sdk (client.batch.*; the xAI Batch API does not use the OpenAI format, the OpenAI SDK does not apply), and the Responses API takes precedence over Chat Completions, a legacy endpoint at xAI. Sources: Batch API · REST Reference · Batch Pricing.

Bulk Multimodal Generation

The Batch API isn’t limited to text. You can submit image generations and edits, plus video generations, edits, and extensions. This capability opens the door to complete multimodal pipelines: write descriptions and produce their visuals in a single operation.

Batch Image Generation

The /v1/images/generations endpoint works in a batch just like in synchronous mode. Select the format with aspect_ratio, the definition with resolution ("1k", "1.5k", or "2k"), and the number of images with n:

{"custom_id": "img-001", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Minimalist logo for a fintech startup, white background, vector style", "n": 1, "aspect_ratio": "1:1", "resolution": "1k"}}
{"custom_id": "img-002", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Isometric illustration of a datacenter", "n": 1, "aspect_ratio": "16:9", "resolution": "1k"}}

Batch Image Editing

The /v1/images/edits endpoint modifies an existing image, passed in an image object: a url (public address or base64-encoded data) or the file_id of an uploaded file.

{"custom_id": "edit-001", "method": "POST", "url": "/v1/images/edits", "body": {"model": "grok-imagine-image-2.0", "prompt": "Replace the background with a solid white background", "image": {"url": "https://example.com/photo.jpg"}}}

In batch mode, editing helps process a catalog: harmonize backgrounds, add an element, or apply the same retouch to hundreds of visuals.

Batch Video Generation

The /v1/videos/generations (or /v1/videos) endpoint generates videos from 1 to 15 seconds (duration, 8 by default), in 480p, 720p, or 1080p:

{"custom_id": "vid-001", "method": "POST", "url": "/v1/videos/generations", "body": {"model": "grok-imagine-video-1.5", "prompt": "Smooth animation of a bar chart growing progressively", "duration": 8, "resolution": "720p"}}

Video processing is heavier than text or images, so these requests may take longer within the batch.

Video Editing and Extension

The /v1/videos/edits endpoint modifies an existing video, and /v1/videos/extensions extends it by a segment of 2 to 10 seconds. Pass the source video in a video object (URL of a .mp4 file, or file_id):

{"custom_id": "vid-edit-001", "method": "POST", "url": "/v1/videos/edits", "body": {"model": "grok-imagine-video", "prompt": "Slow down the scene", "video": {"url": "https://example.com/clip.mp4"}}}
{"custom_id": "vid-ext-001", "method": "POST", "url": "/v1/videos/extensions", "body": {"model": "grok-imagine-video", "prompt": "The camera slowly pulls back and reveals a sunset", "video": {"url": "https://example.com/clip.mp4"}, "duration": 6}}

Using the Python SDK

The SDK prepares these requests with dedicated methods, then adds them to the batch like text requests:

from xai_sdk import Client

client = Client()
batch = client.batch.create(batch_name="catalog_visuals")

requetes = [
    client.image.prepare(
        prompt="Product shot of wireless headphones, dark background, studio lighting",
        model="grok-imagine-image-2.0",
        batch_request_id="prod-42-img",
    ),
    client.video.prepare(
        prompt="The headphones rotate slowly on a turntable, dramatic lighting",
        model="grok-imagine-video-1.5",
        batch_request_id="prod-42-vid",
    ),
]
client.batch.add(batch_id=batch.batch_id, batch_requests=requetes)

Multimodal Content Pricing

Important point: the batch discount applies only to eligible text models. Images and videos are billed at the standard rate, even in batch mode—as of November 2, 2026, $0.04 per image with grok-imagine-image-2.0 ($0.02 with grok-imagine-image), and $0.08 per second of video with grok-imagine-video-1.5 ($0.02 in the -lite version, $0.05 with grok-imagine-video).

The benefit of batches for multimodal content isn’t pricing but operational: submit hundreds of generations in one operation, without managing as many calls or hitting rate limits.

Result URL Expiration

Image and video results are provided as signed URLs that expire after one hour. This is a critical constraint: download the files as soon as you retrieve the results.

import mimetypes

import requests


def telecharger_medias(resultats, dossier):
    """Downloads images and videos as soon as results are retrieved."""
    for r in resultats:
        reponse = r.proto.response
        if reponse.HasField("image_response"):
            url = r.image_response.url
        elif reponse.HasField("video_response"):
            url = r.video_response.url
        else:
            continue  # text result
        fichier = requests.get(url, timeout=120)
        fichier.raise_for_status()
        type_mime = fichier.headers.get("Content-Type", "").split(";")[0]
        extension = mimetypes.guess_extension(type_mime) or ".bin"
        with open(f"{dossier}/{r.batch_request_id}{extension}", "wb") as f:
            f.write(fichier.content)

Never store signed URLs for later use: save the files in your own storage (S3, GCS, local disk).

Mixed Multimodal Pipeline

A concrete use case: produce complete product sheets, text and visual, in the same batch:

{"custom_id": "prod-42-desc", "method": "POST", "url": "/v1/responses", "body": {"model": "grok-4.3", "input": "Write a marketing description for a high-end wireless headphone.", "max_output_tokens": 300}}
{"custom_id": "prod-42-img", "method": "POST", "url": "/v1/images/generations", "body": {"model": "grok-imagine-image-2.0", "prompt": "Product shot of premium wireless headphones, dark gradient background, studio lighting"}}

A common prefix in the identifiers (prod-42-desc, prod-42-img) makes it easy to group text and image results for the same product.

Key Takeaways

Images (generation, editing) and videos (generation, editing, extension) work in batches
Parameters match the API: aspect_ratio, resolution, image and video objects
Images and videos remain at standard rates, without batch discounts
Signed result URLs expire after one hour: download immediately
A common prefix in identifiers groups results for the same product