Video API

Generate video asynchronously

Run Seedance 2.5, Seedance 2.0, Seedance 2.0 Fast, and Seedance 2.0 Mini with four pre-release workflows and one task lifecycle.

Get started

Choose a workflow

Generate from text, one image, first and last frames, or multimodal references.

Create a task

Send the model, route, prompt, output settings, and conditional reference fields.

Poll or use webhooks

Use the returned poll_url until the task succeeds. Pre-release webhook endpoints are configured during onboarding.

Create endpoint

POSThttps://api.mlmux.com/v1/videos/generations

Generation modes

Request example

curl https://api.mlmux.com/v1/videos/generations \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "seedance-2.5",
  "route_mode": "official-cheap",
  "prompt": "A cinematic tracking shot at sunrise, natural motion and warm backlight",
  "mode": "text_to_video",
  "ratio": "16:9",
  "resolution": "1080p",
  "duration": 10,
  "generate_audio": true
}'

Parameters

Field	Type	Required	Description
`model`	string	Yes	One of the four Seedance model IDs below.
`prompt`	string	Yes	Scene, motion, camera, lighting, timing, and audio direction.
`route_mode`	string	No	`official`, `official-cheap` (default), or `mix`.
`mode`	string	No	Defaults to `text_to_video`; use an exact mode shown above.
`ratio`	string	Yes	`1:1`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9`, or supported `adaptive`.
`resolution`	string	Yes	Must be supported by the selected model.
`duration`	integer	Yes	Clip length from 4 through 30 seconds.
`generate_audio`	boolean	No	Generate synchronized audio with the clip.
`image_url` / `image_urls`	string / string[]	Conditional	One image for image mode; up to 9 images for multimodal reference.
`first_frame_url` + `last_frame_url`	string	Conditional	Both are required for `first_last_frame`; two ordered `image_urls` also work.
`video_urls` / `audio_urls`	string[]	Conditional	Up to 3 of each in `multi_ref`; 12 references combined.

Model capabilities

Model	Resolution	Ratio	Duration
`seedance-2.5`	480p · 720p · 1080p	adaptive + 6 ratios	4–30s
`seedance-2.0`	480p · 720p · 1080p · 4K	6 fixed ratios	4–30s
`seedance-2.0-fast`	480p · 720p	6 fixed ratios	4–30s
`seedance-2.0-mini`	480p · 720p	adaptive + 6 ratios	4–30s

All four models support all four generation modes, synchronized audio, and the three MLMux routing tiers.

Route mode

Every model supports the same three route tiers: official, official-cheap, and mix. New requests default to official-cheap. A request stays within the selected tier and never silently crosses into another tier.

officialDirect official-provider route

official-cheapLower-cost official route · default

mixMixed upstream pool for price and capacity

Task lifecycle

Video creation always returns HTTP 202 Accepted. Save the returned id, then poll the model-specific URL below. Terminal states are succeeded and failed.

GEThttps://api.mlmux.com/v1/videos/generations/{task_id}

curl https://api.mlmux.com/v1/videos/generations/task_01J... \
  -H "Authorization: Bearer $MLMUX_API_KEY"

Accepted

{
  "id": "task_01J...",
  "object": "video.generation.task",
  "status": "queued",
  "model": "seedance-2.5",
  "poll_url": "/v1/videos/generations/task_01J...",
  "progress": 0,
  "estimated_charge_credits": 1.84
}

Completed

{
  "id": "task_01J...",
  "status": "succeeded",
  "progress": 100,
  "video": "https://cdn.mlmux.com/assets/...mp4",
  "result_payload_url": "https://cdn.mlmux.com/assets/...json"
}

Webhooks

Configure once in Console

Create a signed webhook endpoint in Console → Webhooks, save its one-time signing secret, and subscribe to request.succeeded and/or request.failed.

Common errors

HTTP	Code	Meaning
400	`invalid_video_request`	A mode, reference count, ratio, resolution, or duration is invalid.
401	`unauthorized`	The bearer token is missing or invalid.
402	`insufficient_credits`	Add credits before creating another task.
403	`forbidden_asset_reference`	An `asset://` reference is not owned by this account.
404	`task_not_found`	The task does not exist or belongs to another account.
502	`model_unavailable`	The selected route has no healthy upstream capacity.