API reference
Generate a video
Create a video job with any model on the Video Router.
POST /v1/video-router/generate
Host https://api.open.sume.com · Auth API key
Starts a video job with the model you name and returns at once. Video takes from about a minute to several, so a webhook is usually better than tight polling.
Request
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer <key>. Or send x-api-key. |
Content-Type | string | Yes | application/json |
Idempotency-Key | string | No | 1–255 printable ASCII. Makes a retry return the original job. See Idempotency. |
Body
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | An id from List video models, such as seedance-2.5 or kling-3, or auto to let Sume pick. |
prompt | string | Usually | What happens in the shot. Optional on auto and on a few edit models. |
duration | integer | No | Seconds. Each model lists its range in capabilities.duration_seconds (seedance-2.5: 4–30). |
resolution | string | No | One the model lists, such as 480p, 720p, 1080p. |
aspect_ratio | string | No | 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, auto or adaptive, where listed. |
image_url | string | No | First frame (HTTPS) for image-to-video. |
end_image_url | string | No | Last frame. Needs image_url. |
video_url | string | No | Source clip for video-to-video models. |
audio_url | string | No | Speech for lip-sync models. |
reference_image_urls | string[] | No | 1–10 reference images, where the model takes them. |
reference_video_urls | string[] | No | 1–5 reference clips, where the model takes them. |
generate_audio | boolean | No | Ask for a soundtrack, on models that make one. |
mode | string | No | async (default), webhook, sync or subscribe. See How the API works. |
webhook_url | string | No | Public HTTPS URL for the terminal callback. Used with mode: "webhook". |
wait_timeout_seconds | integer | No | 0–30. How long sync / subscribe waits before answering. |
metadata | object | No | Your own key-value data, stored on the job. Not sent to the model. |
Example
Generate a video
POST /v1/video-router/generate
Required
Response
202 Accepted
The response has the same shape as Generate an image: request_id, the job (with type: "video_generation"), and status_url, result_url, cancel_url, next_poll_after_seconds.
Errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing, unknown for the model, or out of range. |
| 400 | concurrency_limit_reached | Your workspace is at its jobs-in-flight cap. |
| 401 | unauthorized | No key, or the key is wrong or revoked. |
| 402 | insufficient_funds | Your balance cannot cover the price. details has required_usd and available_usd. |
| 409 | idempotency_conflict | The Idempotency-Key was used for a different request. |
| 429 | rate_limited | Too many requests for your key in this window. |
| 503 | database_busy | A short overload. Retry after retry-after. |