Seedance
Seedance is ByteDance’s video model line. Each version generates a clip from a text prompt or from a starting image, 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.
- Clips with sound. The model generates a track with the picture unless you turn it off.
Models
One model ID serves both tasks. 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.
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.
string
required
The model ID:
dreamina-seedance-2-5-260628.array
required
The prompt and, on image-to-video, the first frame. Put the
text item first.string
default:"720p"
The output tier:
480p or 720p. All tasks. A larger frame uses more video tokens.boolean
default:"true"
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.string
required
The task ID. It starts with
cgt-. Poll GET /v1/bytedance/contents/generations/tasks/{task_id} with it.Poll
string
required
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.string
The URL of the clip. Present only when
status is succeeded. The URL expires. Download the clip as soon as the task succeeds.object
The failure detail. Present when the task did not succeed. Read it before you resubmit.
integer
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
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