Seedance
Seedance is ByteDance’s video model line. Each version generates a clip from a text prompt, from a starting image or from reference media, and can score the clip with generated audio. Generation is asynchronous. You submit a task, poll it until the status is terminal, then download the clip. The route mirrors ByteDance’s own API, so the request and response shapes are the provider’s.Best for
- Prompt-driven scenes. A usable clip from a written description, with no shoot and no source footage.
- Animating a still. A first frame fixes the composition and the prompt drives the motion.
- Guiding a clip with references. Reference images, a video or audio steer the subject, motion or sound without fixing the first frame.
- Clips with sound. The model generates a track with the picture unless you turn it off.
Models
One model ID serves every task. The items in
content[] select the task. A text item alone gives text-to-video. A text item plus a first_frame image item gives image-to-video. A text item plus one or more reference items gives reference-to-video. A request cannot mix first or last frame items with reference items; that request returns a 400.
On image-to-video the output shape follows the first frame. Crop the image to the shape you want before you upload it.
Endpoints
The poll route is the submit route with the task ID appended.
Request
Send your API key in theX-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application.
The prompt, plus the first frame on image-to-video or the reference media on reference-to-video. Put the
text item first.The clip length in seconds, as a whole number. All tasks. The minimum is 4. A longer clip uses more video tokens.
The output tier:
480p or 720p. All tasks. A larger frame uses more video tokens.Send
false for a silent clip. All tasks. The flag is a billing dimension: a clip with sound and a silent clip are priced differently.Response
Submit
A 200 status means that the provider accepted the task. It does not mean that the clip is ready.The task ID. Treat it as an opaque string. Poll
GET /v1/bytedance/contents/generations/tasks/{task_id} with it.Poll
queued or running while the task runs. succeeded, failed, cancelled or expired when it ends. Poll until you read one of the four terminal values.The URL of the clip. Present only when
status is succeeded. The URL expires. Download the clip as soon as the task succeeds.The number of video tokens the clip used. Present when
status is succeeded. Seedance is billed by this count, so the cost is known when the task completes.Example
Submit, poll, download. The submit and the poll use the same path. The poll appends the task ID.type set to image_url and role set to first_frame, with the image URL under image_url.url. The body below replaces the submit body in the example.
Image-to-video
reference_* role. The body below uses a reference image and a reference audio clip. Do not add a first_frame item to a reference request.
Reference-to-video
Tips
- Describe motion and camera, not just the scene. A static description gives the model nothing to animate.
- Keep the prompt to one clear action. Busy, multi-event prompts are harder to render cleanly.
- Draft at 480p to settle the wording, then re-run the same prompt at 720p. A smaller frame uses fewer video tokens.
- Decide about audio before you run. The flag changes the price, so a silent draft is the cheaper way to test a prompt.
- Poll every 5 seconds at first, then back off to 30 seconds. Polls are free and never use a concurrency slot.
Errors and limits
A 200 status on submit means that the provider accepted the task. It does not mean that the task succeeded. A task that fails later ends withstatus set to failed, cancelled or expired, and error explains why. Read it before you resubmit.
A failed submit returns an HTTP error status. See Error codes.
A 5xx status or a timeout on submit does not tell you whether the task was created. Never resubmit blindly. If the submit returned an id, poll it. If it returned nothing, check your credits before you try again.
ByteDance applies these limits to each first or last frame image you attach:
- 300 to 6,000 pixels on each side
- An aspect ratio, width over height, between 0.4 and 2.5
- Under 30 MB per file
- First or last frame items cannot be mixed with reference items.
- A reference video must be a web URL. A
data:URI returns a 400. - A reference audio clip can be up to 30 seconds long.
durationis 4 seconds or more.