Video generation

Generate, edit, extend, and reference videos through xAI Grok Imagine batch endpoints with Batchwork's signed-URL video results.

Video batches are supported through xAI (Grok Imagine) only. xAI is currently the only provider whose batch API accepts video generation. OpenAI’s Videos API (Sora) is deprecated (shutting down September 24, 2026), so Batchwork deliberately doesn’t support it; Google’s Veo models aren’t batch-compatible. Other providers raise UnsupportedProviderError before any network request.

CLI

Use batchwork submit videos to return after registration or batchwork run videos for the complete lifecycle. JSON, JSONL, CSV, and text sources map to BatchVideoRequest; each line of text input is one prompt.

batchwork --json run videos prompts.txt \
  --model xai/grok-imagine-video \
  --aspect-ratio 16:9 \
  --duration 8 \
  --resolution 1280x720

CSV columns are custom_id, required prompt, aspect_ratio, duration, and resolution. More than 20 requested videos trips the soft volume gate and requires --allow-large-batch.

Video results are signed URLs that expire about one hour after completion. The CLI never materializes videos; --output-dir remains image-only.

Generation

from batchwork import BatchVideoRequest, Batchwork

async with Batchwork() as client:
    job = await client.batch_videos(
        model="xai/grok-imagine-video",
        requests=[
            BatchVideoRequest(
                custom_id="clip-1",
                prompt="A slow pan across a neon-lit city at night.",
                aspect_ratio="16:9",
                duration=8,
                resolution="1280x720",
            )
        ],
    )
    await job.wait(timeout=3600)
    videos = (await job.collect())[0].videos

Generation lines target /v1/videos/generations. Canonical aspect_ratio uses WIDTH:HEIGHT, duration is a positive second count, and canonical resolution maps 1280x720 to 720p and 854x480/640x480 to 480p. provider_options["xai"]["imageUrl"] supplies a start image.

Edits, extensions, and references

provider_options["xai"] routes individual lines to other endpoints, mirroring the AI SDK’s xAI video model:

BatchVideoRequest(
    custom_id="extend-1",
    prompt="Continue the same camera move for four more seconds.",
    provider_options={
        "xai": {"mode": "extend-video", "videoUrl": "https://example.com/clip.mp4"}
    },
)

Edit and extension lines require videoUrl; reference-to-video lines require referenceImageUrls. Batchwork is strict about incompatible settings and fails locally rather than dropping them: duration on edits, aspect_ratio/resolution on edits or extensions, and a canonical resolution that collides with provider_options["xai"]["resolution"] all raise errors before upload.

Result shape

result.videos  # list[BatchVideo] | None

A BatchVideo contains a url and optional duration_seconds. URLs are signed and expire about one hour after completion; download or relay them promptly.

Unsupported providers

Anthropic, Azure, Google Gemini, Groq, Mistral, OpenAI, and Together AI video submissions fail locally.

See Provider overview and Results.