Skip to main content

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 the X-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.
To animate a still, append an item with 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 with status 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
Seedance is billed by the number of video tokens the finished clip uses. The charge is known when the task completes, not before it starts. A longer or larger clip uses more tokens, and the audio flag changes the rate. Every task counts toward the simultaneous-jobs cap of your plan. See Rate limits, Credits & pricing and the Partner models overview.