Video model router API: calling sume/auto on POST /v1/videos

To use Sume as a video model router over HTTP, send POST /v1/videos with model set to sume/auto. Sume picks the model family, returns a job, and you poll it like any other video job. The poll response reports sume/auto, not the family that ran. To choose the model yourself, replace the value with a catalog id.

What does the request look like?

The body follows the Video generation docs. model and prompt are required; aspect_ratio and duration are optional. Sending an Idempotency-Key makes a retry safe, and a replay returns the original job.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: router-demo-001" \
  -d '{
    "model": "sume/auto",
    "prompt": "A vertical UGC-style product clip on a desk, natural light",
    "aspect_ratio": "9:16",
    "duration": 5
  }'

How do I poll and download the result?

Take the polling_url from the response, or call GET /v1/videos/<job_id> with the same bearer token. When the status is completed, download from unsigned_urls[0]. The same job is also visible at GET /v1/jobs/{id}/status and GET /v1/jobs/{id}/result.

Which routes reach the router?

Several URLs lead to the same Auto pipe, so pick by what you are integrating.

How do I get a callback instead of polling?

Pass callback_url, which must be HTTPS. Sume POSTs to it when the job reaches a terminal state, signs the raw JSON body, and sends x-sume-webhook-timestamp and x-sume-webhook-signature headers. The payload is Sume's standard job envelope, not the OpenRouter video.generation.* one. Verify the signature with a non-empty secret before you trust the body.

Which fields will a router request reject?

Every v1 model reports supported_sizes: null, so an exact size returns 400 unsupported_parameter; use resolution and aspect_ratio instead. The legacy /v1/video-router/generate route returns Sume's { "data": ... } job envelope rather than the /v1/videos shape, so do not mix the two parsers in one client.

What are the limits of routing?

Auto's create controls default to 720p and 8 seconds, with 3 to 10 second clips at 16:9 or 9:16, per the Video Router docs. A longer clip needs a pinned model: seedance-2.5 accepts 4 to 30 seconds and wan-3.0 2 to 30. Money is reserved on submit at provider list times 1.25. To see which ids you can pin, call GET /v1/videos/models with your API key; each entry reports its supported resolutions, aspect ratios and durations, so a client can validate a request before it spends anything.

If you are moving an existing integration, see migrate Video 1.0 to sume/auto. For the OpenRouter-shaped wire, see the OpenRouter-compatible video API.