Image generation

Generate image batches through OpenAI, Google Gemini, and xAI with Batchwork's normalized image result collection APIs.

Image-output batches are supported through OpenAI, Google Gemini, and xAI. Images supplied to a text request are input media and use batch(), not batch_images().

CLI

Use batchwork submit images to return after registration or batchwork run images for the complete submit, wait, and results lifecycle. JSON, JSONL, CSV, and text sources map to BatchImageRequest; missing custom_id values are generated deterministically.

batchwork --json run images prompts.jsonl \
  --model openai/gpt-image-2 \
  --n 2 \
  --size 1536x1024

Machine output preserves normalized image data and URLs. Human output shows image counts but never prints inline data or complete URLs. Result retrieval does not download URLs or write local files unless --output-dir is explicit:

batchwork --json results bw_0123456789abcdef0123456789abcdef \
  --output-dir ./generated-images

The output target must be absent or an empty non-symlink directory. Batchwork writes each completed image atomically and maintains manifest.json; inline data wins when a provider returns both data and a URL.

OpenAI

from batchwork import BatchImageRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch_images(
        model="openai/gpt-image-2",
        requests=[
            BatchImageRequest(
                custom_id="bike",
                prompt="A red bicycle leaning against a brick wall.",
                n=2,
                size="1536x1024",
                provider_options={
                    "openai": {"outputFormat": "webp", "quality": "high"}
                },
            )
        ],
    )
    await job.wait(timeout=3600)
    images = (await job.collect())[0].images

OpenAI image batches target /v1/images/generations and normalize inline base64 results. n and model-supported size values are accepted. Provider options are model-specific: DALL-E 3 supports quality, style, and user; DALL-E 2 supports user; GPT Image models support background, moderation, outputFormat, outputCompression, quality, and user. Generic aspect_ratio and seed are rejected. Image editing is outside batch_images().

Google Gemini

from batchwork import BatchImageRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch_images(
        model="google/gemini-3-pro-image-preview",
        requests=[
            BatchImageRequest(
                custom_id="forest",
                prompt="A sunlit forest path in watercolor.",
                aspect_ratio="16:9",
                seed=42,
            )
        ],
    )
    await job.wait(timeout=3600)
    images = (await job.collect())[0].images

Google image batches use the inline :batchGenerateContent operation and return images from inline response parts.

• Exactly one image per request is supported (n=1).
• aspect_ratio and seed are serialized.
• Generic size is not serialized.
• Imagen :predict models are outside Batchwork’s batch image scope.
• File-mode batch results are not supported; Batchwork raises instead of silently dropping them.

xAI

async with Batchwork() as client:
    job = await client.batch_images(
        model="xai/grok-imagine-image",
        requests=[
            BatchImageRequest(
                custom_id="city",
                prompt="A quiet futuristic city at dawn.",
                n=2,
                aspect_ratio="16:9",
            )
        ],
    )
    await job.wait(timeout=3600)

    async for result in job.results():
        for image in result.images or []:
            if image.data is not None:
                await save_base64(image.data, image.media_type)
            elif image.url is not None:
                await download_promptly(image.url)

xAI requests force a base64-oriented response format, but normalization accepts image data, a url, or both. Provider-returned URLs may be signed and short-lived.

• n and generic aspect_ratio are supported.
• Generic size and seed are not serialized.
• xAI provider options include output format, sync mode, resolution, quality, user, and provider-level aspect ratio.

Result shape

Each successful BatchResult may expose:

result.images  # list[BatchImage] | None

A BatchImage contains data, url, or both plus an optional media_type. Provider-specific response details remain available in result.response.

Unsupported providers

Anthropic, Groq, Mistral, and Together AI image-output submissions fail locally.

See Provider overview and Results.