Generate
Video
One endpoint for video models, lip-sync and captions. Video takes from about a minute to several, so plan to poll slowly or use a webhook.
POSThttps://api.dev.sume.com/v1/video-router/generate
Request
Same headers as images, Idempotency-Key included. Durations, resolutions and inputs differ by model; check the model's capabilities in Models before you send.
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model id, such as seedance-2.5 or kling-3. |
prompt | string | No | What happens in the shot. Most models need it; a few edit and lip-sync models do not take it. |
duration | integer | No | Seconds, within the model's duration_seconds range. |
resolution | string | No | One the model lists, such as 480p, 720p, 1080p. |
aspect_ratio | string | No | 16:9, 9:16, 1:1 and others, where listed. |
image_url | string | No | First frame for image to video, or the face for image lip-sync. |
end_image_url | string | No | Last frame. Needs image_url. |
video_url | string | No | Source clip for video to video, video lip-sync and captions. |
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. |
webhook_url | string | No | Public HTTPS URL called when the job ends. |
metadata | object | No | Your own key-value data, stored on the job. |
Text to video
curl -X POST https://api.dev.sume.com/v1/video-router/generate \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"model": "seedance-2.5",
"prompt": "Steam rises from a coffee cup as the camera slowly pushes in",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}'Image to video
Put the first frame in image_url. Upload a local picture first with File uploads.
{
"model": "kling-3",
"prompt": "The kite drifts gently in the wind, waves roll in",
"image_url": "https://media.sume.com/assets/asset_6f1d0c2b/source.png",
"duration": 5
}Lip-sync and captions
Lip-sync models make a face say an audio track: image_url or video_url for the face, audio_url for the speech, and usually a duration as long as the audio. Captions models take a video_url.
{
"model": "veed-fabric-1.0",
"image_url": "https://media.sume.com/assets/asset_face/source.jpg",
"audio_url": "https://media.sume.com/assets/asset_voice/source.wav",
"duration": 8,
"resolution": "480p"
}Long jobs
A video can still be running after your own deadline. Check it again later with the same job id; do not submit again, which starts and charges a second job.
Response
{
"data": {
"request_id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"job": {
"id": "job_7513b52d-3669-4ffe-b317-8b02000715eb",
"type": "video_generation",
"status": "queued",
"model": "seedance-2.5",
"created_at": "2026-10-21T02:31:52.075Z",
"result": null,
"error": null
},
"status_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/status",
"result_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/result",
"events_url": "https://api.dev.sume.com/v1/jobs/job_7513b52d-3669-4ffe-b317-8b02000715eb/events",
"cancel_url": null,
"cancelable": false,
"next_action": "poll_status",
"next_poll_after_seconds": 2,
"terminal": false,
"idempotency_hit": false
}
}Errors
| Status | code | When |
|---|---|---|
| 400 | invalid_request | A field is missing, unknown for the model or out of range. |
| 401 | unauthorized | No key, or the key is wrong or revoked. |
| 402 | insufficient_funds | The workspace balance does not cover the price. |
| 409 | idempotency_conflict | The Idempotency-Key was used for a different request. |
| 429 | queue_full | The workspace has as many jobs in flight as it may. |
| 429 | rate_limited | Too many requests for this key right now. |