Image editing

Edit image batches through OpenAI and xAI with Batchwork's file-ID and URL image references, optional masks, and normalized image results.

Image-edit batches are supported through OpenAI and xAI. Source images are passed as references — an OpenAI Files file_id or an image_url — and edited results land on result.images exactly like image generation.

CLI

Use batchwork submit image-edits to return after registration or batchwork run image-edits for the complete submit, wait, and results lifecycle. JSON, JSONL, and CSV sources map to BatchImageEditRequest; text input is not supported for image edits.

batchwork --json run image-edits edits.csv \
  --model openai/gpt-image-2 \
  --size 1536x1024

CSV columns are custom_id, required prompt, exactly one of image_url/file_id, optional mask_url or mask_file_id (at most one), n, and size. Multi-image edits require JSON or JSONL. --output-dir materialization works the same as image generation.

OpenAI

from batchwork import BatchImageEditRequest, BatchImageUrlRef, Batchwork

async with Batchwork() as client:
    job = await client.batch_image_edits(
        model="openai/gpt-image-2",
        requests=[
            BatchImageEditRequest(
                custom_id="recolor",
                prompt="Replace the wall color with deep green.",
                images=[BatchImageUrlRef(image_url="https://example.com/bike.png")],
                size="1536x1024",
            )
        ],
    )
    await job.wait(timeout=3600)
    images = (await job.collect())[0].images

OpenAI edit batches target /v1/images/edits. images accepts BatchImageFileRef (file_id) and BatchImageUrlRef (image_url) entries, and an optional mask uses the same reference shape. n and model-supported size values are accepted.

xAI

job = await client.batch_image_edits(
    model="xai/grok-imagine-image",
    requests=[
        BatchImageEditRequest(
            custom_id="recolor",
            prompt="Replace the wall color with deep green.",
            images=[BatchImageUrlRef(image_url="https://example.com/bike.png")],
        )
    ],
)

xAI image edits accept image URLs only. file_id references, mask, and canonical size are rejected locally before any network request; use provider_options["xai"]["aspect_ratio"] for the output shape instead. One image serializes as image; several serialize as images.

Result shape

result.images  # list[BatchImage] | None

Each BatchImage contains data, url, or both plus an optional media_type, identical to generation results. Provider-returned URLs may be signed and short-lived.

Unsupported providers

Anthropic, Azure, Google Gemini, Groq, Mistral, and Together AI image-edit submissions fail locally.

See Image generation, Provider overview, and Results.