Eve library

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

Guide

Revision 1

On this page

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).

text
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.