Video generation: the ticket pattern lands on Sora, Veo, and grok-imagine

Job-shaped on every wire, so video reuses batch's idiom: video_generate
returns a VideoJob (wait / result / re-attach by id / enumerate where
the wire lists). One closed status vocabulary; wire words stay in
provider_data. Results are honest VideoParts: bytes where the wire
streams them (Sora content endpoint; Veo's file URI is key-bound — 403
without the header, verified live), a public URL on xAI. seconds maps
Sora/Veo duration knobs and raises on xAI; input images raise on all
three until live-receipted (xAI silently ignores unknown fields — the
pixel-check lesson). No list endpoint on xAI: the ticket is the only
copy, said in the error. sora-/veo- routing rules; EndpointSupport
gains video; two serde kinds; vet video_op pair; async twins; recipe 14
graduates with all-real outputs (recipes 15-18 renumbered); live-proven
on all three wires by re-attaching to today's captured jobs.

Author: MaximeRivest

conformance/check_serde_fixtures.py

@@ -64,6 +64,8 @@ class SerdeResult:
     "image_generation_response": (serde.image_generation_response_from_dict, serde.image_generation_response_to_dict),
     "speech_generation_request": (serde.speech_generation_request_from_dict, serde.speech_generation_request_to_dict),
     "speech_generation_response": (serde.speech_generation_response_from_dict, serde.speech_generation_response_to_dict),
+    "video_generation_request": (serde.video_generation_request_from_dict, serde.video_generation_request_to_dict),
+    "video_job": (serde.video_job_from_dict, serde.video_job_to_dict),
 }
 
 

conformance/serde/canonical.json

@@ -1224,6 +1224,48 @@
      "modelVersion": "gemini-2.5-flash-preview-tts"
     }
    }
+  },
+  {
+   "id": "video_generation_request.minimal",
+   "kind": "video_generation_request",
+   "value": {
+    "model": "grok-imagine-video",
+    "prompt": "A red ball bounces once"
+   }
+  },
+  {
+   "id": "video_generation_request.full",
+   "kind": "video_generation_request",
+   "value": {
+    "model": "sora-2",
+    "prompt": "A red ball bounces once",
+    "seconds": 4,
+    "extensions": {
+     "size": "720x1280"
+    }
+   }
+  },
+  {
+   "id": "video_job.minimal",
+   "kind": "video_job",
+   "value": {
+    "id": "video_1",
+    "status": "queued"
+   }
+  },
+  {
+   "id": "video_job.full",
+   "kind": "video_job",
+   "value": {
+    "id": "models/veo-3.1-lite-generate-preview/operations/0008ar3b1ksa",
+    "status": "completed",
+    "progress": 100,
+    "created_at": "2026-09-01T12:46:16Z",
+    "model": "sora-2",
+    "provider_data": {
+     "status": "done"
+    }
+   }
   }
  ]
 }

docs/cookbooks/01-first-request.md

@@ -174,7 +174,7 @@ one call in, one typed `Response` out.
   again.
 - **Direct LMs are for configuration, not preference.** Reach for them
   when you need a custom `base_url` or compat preset (ollama, vLLM —
-  recipe [14](15-local-and-compatible-servers.md)) or when you are a
+  recipe [14](16-local-and-compatible-servers.md)) or when you are a
   library taking an LM object from your caller.
 - **Async direct LMs exist too**: `AsyncOpenAILM`, `AsyncAnthropicLM`,
   `AsyncGeminiLM`, same constructors, awaitable `complete`.
@@ -188,4 +188,4 @@ one call in, one typed `Response` out.
 - [04 — Controlling generation](04-generation-config.md)
 - [05 — Streaming](05-streaming.md)
 - [Using the router](../using-the-router.md) — grammar, catalogs, credentials
-- [16 — Errors, retries & testing](16-errors-and-testing.md)
+- [17 — Errors, retries & testing](17-errors-and-testing.md)

docs/cookbooks/03-system-prompts.md

@@ -107,7 +107,7 @@ content is instructions, not transcript. On the wire:
 
 `Message.developer()` is a fourth role alongside `user`, `assistant`,
 and `tool`. OpenAI keeps it as `role: "developer"` (configurable via
-compat — older Chat Completions servers want `"system"`; recipe 15).
+compat — older Chat Completions servers want `"system"`; recipe 16).
 Anthropic and Gemini providers convert it to a user message whose text
 is prefixed with `[developer]\n`. That is a convention, not an API
 guarantee: on those providers a developer message has whatever authority
@@ -140,7 +140,7 @@ request, your messages verbatim — what you build is what is sent.
 - **Fail-fast validation.** `Request(system="")` raises `ValueError`
   and protocol parts (tool calls, citations) in `system` raise
   `TypeError` — both at construction, before any network call
-  (recipe 16).
+  (recipe 17).
 - **System parts are text-only in practice.** All three providers
   flatten system parts to text before sending. Images or documents in
   instructions belong in a `user` or `developer` message instead
@@ -151,5 +151,5 @@ request, your messages verbatim — what you build is what is sent.
 - [02 — Multi-turn conversations](02-conversations.md)
 - [04 — Controlling generation](04-generation-config.md)
 - [11 — Prompt caching](11-caching.md)
-- [15 — Local & OpenAI-compatible servers](15-local-and-compatible-servers.md)
+- [16 — Local & OpenAI-compatible servers](16-local-and-compatible-servers.md)
 - [Using the router](../using-the-router.md)

docs/cookbooks/04-generation-config.md

@@ -174,12 +174,12 @@ other providers.
   preferred.
 - **Async mirror.** Identical `Config`, `await AsyncLMRouter().complete(request)`.
 - **Provider-only knobs** (`seed`, `frequency_penalty`, …) go in
-  `Config(extensions=…)` — [recipe 17](17-provider-passthrough.md).
+  `Config(extensions=…)` — [recipe 18](18-provider-passthrough.md).
 
 ## See also
 
 - [03 — System & developer prompts](03-system-prompts.md)
 - [05 — Streaming](05-streaming.md)
 - [08 — Structured output](08-structured-output.md) — `response_format` in depth
-- [17 — Provider passthrough](17-provider-passthrough.md)
+- [18 — Provider passthrough](18-provider-passthrough.md)
 - [Using the router](../using-the-router.md)

docs/cookbooks/05-streaming.md

@@ -186,12 +186,12 @@ the layer above.
 - **Replay.** `lm15.result.response_to_events(response)` converts a
   complete `Response` back into a stream — useful for testing stream
   consumers without a network (recipe
-  [15](16-errors-and-testing.md)).
+  [15](17-errors-and-testing.md)).
 
 ## See also
 
 - [01 — Your first request](01-first-request.md) — keys and the router front door.
 - [06 — Function tools](06-function-tools.md) — tool-call parts surfaced by `ResponseStream`.
 - [10 — Audio, video & reasoning models](10-audio-video-reasoning.md) — thinking deltas.
-- [16 — Errors, retries & testing](16-errors-and-testing.md) — stream errors, offline replay.
+- [17 — Errors, retries & testing](17-errors-and-testing.md) — stream errors, offline replay.
 - [Using the router](../using-the-router.md) — resolution rules and `RouterConfig`.

docs/cookbooks/06-function-tools.md

@@ -218,6 +218,6 @@ which builds one `ToolResultPart` per entry.
 
 - [07 — Built-in provider tools](07-builtin-tools.md)
 - [08 — Structured output](08-structured-output.md)
-- [16 — Errors, retries & testing](16-errors-and-testing.md)
+- [17 — Errors, retries & testing](17-errors-and-testing.md)
 - [Tools from functions](../tools-from-functions.md) — full derivation rules
 - [Using the router](../using-the-router.md)

docs/cookbooks/09-images-and-documents.md

@@ -226,5 +226,5 @@ across all three. See [../using-the-router.md](../using-the-router.md).
 - [02 — Multi-turn conversations](02-conversations.md)
 - [10 — Audio, video & reasoning models](10-audio-video-reasoning.md)
 - [13 — Media generation (images & speech)](13-media-generation.md)
-- [16 — Errors, retries & testing](16-errors-and-testing.md)
+- [17 — Errors, retries & testing](17-errors-and-testing.md)
 - [../using-the-router.md](../using-the-router.md)

docs/cookbooks/10-audio-video-reasoning.md

@@ -229,7 +229,7 @@ does not estimate.
 - [05 — Streaming](05-streaming.md) — `Result.events()` and typed deltas.
 - [09 — Images, PDFs & documents](09-images-and-documents.md) — the
   other media parts, with broader provider support.
-- [14 — Live sessions (realtime)](14-live-sessions.md) — audio out, not
+- [15 — Live sessions (realtime)](15-live-sessions.md) — audio out, not
   just in.
 - [../using-the-type-system.md](../using-the-type-system.md) — parts,
   `Reasoning`, and `Usage` in full.

docs/cookbooks/12-batch-jobs.md

@@ -166,8 +166,8 @@ lm15 never falls back to silently looping `complete()` at full price.
 
 - [13 — Media generation](13-media-generation.md) — the other non-chat
   endpoints.
-- [15 — Local & OpenAI-compatible servers](15-local-and-compatible-servers.md)
-- [16 — Errors, retries & testing](16-errors-and-testing.md) — the
+- [16 — Local & OpenAI-compatible servers](16-local-and-compatible-servers.md)
+- [17 — Errors, retries & testing](17-errors-and-testing.md) — the
   typed error tree entries carry.
-- [17 — Provider passthrough](17-provider-passthrough.md) — reading
+- [18 — Provider passthrough](18-provider-passthrough.md) — reading
   `provider_data`.