# OpenRouter video transport — wire shapes read from the guide, 2026-09-10

Evidence for `182.C.11.01`/`.02`, and a **correction** to what `182.C.11.01`
shipped earlier the same day. Fetched from the official video-generation guide,
which is the documented contract of record (the `create-videos` API-reference
page returned 404 on 2026-09-09).

```
GET https://openrouter.ai/docs/guides/overview/multimodal/video-generation  → 200, 946018 bytes
GET https://openrouter.ai/api/v1/providers                                  → 200, 24428 bytes, 105 providers
```

## Three shapes the phase snapshot recorded loosely

The snapshot in `TODOS/phase-182.md` wrote the reference entry as
`{ type: 'image_url', image_url }`, which reads naturally as a string. It is
not. The guide's own request samples:

```json
"frame_images": [
  { "type": "image_url", "image_url": { "url": "https://example.com/first-frame.png" },
    "frame_type": "first_frame" }
]
```

```json
"input_references": [
  { "type": "image_url", "image_url": { "url": "https://example.com/style-ref.png" } }
]
```

```json
"provider": {
  "options": {
    "google-vertex": {
      "parameters": { "personGeneration": "allow", "negativePrompt": "blurry, low quality" }
    }
  }
}
```

So:

1. **`image_url` is an object `{ url }`**, in both `frame_images` and
   `input_references`. `182.C.11.01` shipped it as a bare string and was
   corrected the same day.
2. **`frame_images` entries carry `frame_type`**, `first_frame` or `last_frame`
   — the field that makes `182.C.11.02` independent of general references rather
   than a variant of them.
3. **`provider` is not a flat map.** It is keyed by PROVIDER SLUG under
   `options`, with the values under `parameters`, and the guide says only the
   options for the matched provider are forwarded. A flat `{ audio: … }` is
   therefore accepted by the API and forwarded to nobody: the take renders
   without the creator's approved speech and reports success. That is the exact
   silent downgrade `182.C.03.07` forbids, arrived at by a shape error rather
   than by a routing decision.

## The provider slug — corrected the same day

The first pass at this concluded the slug was a manual record, on the strength
of the model-id prefixes not all appearing in `GET /api/v1/providers`. That was
the wrong conclusion from the right observation.
**`GET /api/v1/models/{id}/endpoints` answers it**, live and unbilled, and the
full table for all 28 video models is committed as `provider-slugs.json`.

| Model                                                                                   | Slug              |
| --------------------------------------------------------------------------------------- | ----------------- |
| `alibaba/wan-2.7`, `wan-2.6`                                                            | **`atlas-cloud`** |
| `alibaba/wan-3.0`, `-prime`, `happyhorse-1.0`, `-1.1`                                   | `alibaba`         |
| `kwaivgi/kling-v3.0-pro`, `-std`, `kling-video-o1`                                      | `atlas-cloud`     |
| `bytedance/seedance-*` (5 models)                                                       | `seed`            |
| `google/veo-3.1`, `-fast`, `-lite`                                                      | `google-vertex`   |
| `x-ai/grok-imagine-video`, `-1.5`                                                       | `xai`             |
| `minimax/*`, `runway/*`, `heygen/avatar-iv`, `openai/sora-2-pro`, `black-forest-labs/*` | the id prefix     |

**Fifteen of the twenty-eight** do not match their own id prefix — more than
half — so deriving the slug from the id would be wrong more often than right.
The pair worth staring at is `alibaba`: `wan-2.7` is served by AtlasCloud and
`wan-3.0` by Alibaba itself. Nothing in the model id distinguishes them.

`182.C.12.01` shipped `alibaba` for the Wan family a few commits before this was
read, which would have keyed wan-2.7's **audio passthrough under a slug that
serves nothing** — accepted by the API, forwarded to nobody, and a take back
without the creator's approved speech in it. Corrected to `atlas-cloud`, and the
adapter spec now asserts each model's slug against the recorded table rather
than against a literal.

`resolveProviderEndpoints` reads this live and fails closed on a non-200, an
unreadable body, or an empty list; more than one endpoint returns them all with
a null single slug, because that is an ambiguity the caller must record rather
than one this code should resolve.

## Correction to `182.C.10.05`

That item recorded geography, data handling and retention as things "no catalog
carries". True of `GET /api/v1/videos/models`, which is what it was measured
against — but `/api/v1/providers` carries `headquarters`, `datacenters`,
`privacy_policy_url` and `terms_of_service_url`, so part of that record is
DERIVABLE rather than purely manual:

- `headquarters` and `datacenters` are a real, dated input to geographic
  restrictions — though `datacenters` was `null` on the first record inspected,
  so it is a partial source, not a substitute for reading the terms.
- `privacy_policy_url` and `terms_of_service_url` give the manual record its
  `sourceUrl` without a human hunting for it.

Neither field states a retention window or a training policy, so the manual
record still has to be written by a person reading those documents. The
`ManualModelRecord` shape does not change; what changes is that two of its
fields now have a machine-readable starting point.

## Other wire facts confirmed the same day

- Job statuses are `pending`, `in_progress`, `completed`, `failed`. The poll
  response carries `id`, `generation_id`, `polling_url`, `status`,
  `unsigned_urls`, and `usage: { cost, is_byok }`.
- Download is `GET /api/v1/videos/{jobId}/content?index=0` with the Bearer key;
  `index` defaults to 0 and exists for models returning several outputs.
- `generate_audio` "defaults to `true` for models that support audio output" —
  as the phase snapshot said, so an exact-audio request must set it
  deliberately.
- `callback_url` in the request body takes priority over the workspace default.

## Webhook contract, read the same day

Delivery is a POST to `callback_url` with an event envelope, plus an
`X-OpenRouter-Idempotency-Key` header of the form `<job_id>-<status>` "for safe
retry deduplication". The four event types and their payload shape:

```json
{
  "type": "video.generation.completed",
  "created_at": "2026-04-24T12:00:00.000Z",
  "data": {
    "id": "abc123",
    "status": "completed",
    "generation_id": "gen-xyz789",
    "model": "google/veo-3.1",
    "unsigned_urls": [
      "https://openrouter.ai/api/v1/videos/abc123/content?index=0"
    ],
    "usage": { "cost": 0.5, "is_byok": false }
  }
}
```

`.failed`, `.cancelled` and `.expired` carry an `error` string instead of
`unsigned_urls` — `"Content policy violation"`, `"Job was cancelled"`, and
`"Job exceeded maximum time to live"` in the guide's own examples. And the
sentence the receiver is built around:

> `generation_id` and `model` in `data` may be null when a job fails before
> those values are assigned (e.g. an early validation failure).

### Signature

A signing secret is configured per workspace, and **only then** does a delivery
carry `X-OpenRouter-Signature`. The header form is
`t=1234567890,v1=a1b2c3d4...`, and the guide's verification steps are:

1. extract the timestamp (`t`) and hash (`v1`);
2. construct the signed payload `{timestamp},{raw_request_body}` — joined with a
   comma;
3. HMAC-SHA256 it with the signing secret as the key;
4. compare the hex result with `v1`.

The guide's own snippet rejects timestamps older than 300 seconds. Our receiver
rejects future ones by the same margin, because a clock skewed the other way is
the same replay window pointed forward, and it compares in constant time.

Because the signature exists only when a secret is configured, a receiver
without one cannot tell OpenRouter's callback from any other POST. That is why
an unverified delivery never advances a job and the receipt says to poll
instead: the job's real state is knowable from the API, and one request is
cheaper than a wrong belief about a render.

## Cancellation is not exposed — and the 404s prove it

The phase asks for cancellation "where the API exposes it". It does not. Probed
2026-09-10 against a job id that does not exist:

| Request                                            | Status | Body                                                                     |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| `GET /api/v1/videos/nonexistent-job-oshun`         | 404    | `{"error":{"message":"Job nonexistent-job-oshun not found","code":404}}` |
| `DELETE /api/v1/videos/nonexistent-job-oshun`      | 404    | `404 Not Found` (plain text)                                             |
| `POST /api/v1/videos/nonexistent-job-oshun`        | 404    | `404 Not Found` (plain text)                                             |
| `POST /api/v1/videos/nonexistent-job-oshun/cancel` | 404    | `404 Not Found` (plain text)                                             |

The difference in the BODY is the evidence, not the status. A JSON error
envelope means the route exists and the job does not; a plain-text
`404 Not Found` is the router saying there is no such route. The guide documents
no cancellation endpoint either — `cancelled` appears only as a webhook event
type, so a job can _be_ cancelled without us being able to cancel one.

`requestCancellation` therefore throws `CancellationNotExposedError` carrying
this evidence and the probe date, and `CANCELLATION_AVAILABLE` is `false`.
Re-probe before changing either.

## Troubleshooting guidance the poll policy follows

The guide's own words, on the same page:

> Job stays in pending for a long time? Video generation can take several
> minutes depending on the model, resolution, and server load. Continue polling
> at regular intervals.

So exhausting our poll budget is our bound, not the job failing, and
`decidePoll` reports `budget_exhausted` with `jobStillLive: true` rather than
writing a failure into the record.

`Retry-After` appears nowhere in the video guide (0 hits in the page). It is
honoured when present and never depended on.

## Two unbilled credential checks (`182.C.13.04`)

Readiness needs something an import cannot fake. Both of these answer live and
cost nothing:

| Request               | Good key                                                                                                | Revoked key                                              | No key                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------- |
| `GET /api/v1/key`     | 200 with `{ data: { label, limit, limit_remaining, is_free_tier, expires_at, usage, usage_daily, … } }` | 401                                                      | 401                                      |
| `GET /api/v1/credits` | 200 with `{ data: { total_credits, total_usage } }`                                                     | 401 `{"error":{"message":"User not found.","code":401}}` | 401 `"No cookie auth credentials found"` |

Two details worth keeping. The revoked-key and no-key 401s carry **different
messages**, which is why "no credential configured" and "the provider rejected
this credential" are separate signals rather than one. And `label` is a
**partial key** (`sk-or-v1-448...6d2`), so it never enters a readiness result —
`182.C.11.10`'s guard treats `sk-or-` as a marker and a test asserts the result
is clean.

`GET /api/v1/credits` also gave a third independent confirmation of the canary
cost: `total_usage` read 20.968672686 before the render and 21.018672686 after —
exactly $0.05, matching both the predicted price and `usage.cost` in the poll.
