Skip to main content

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 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, plus the first frame on image-to-video or the reference media on reference-to-video. Put the text item first.
integer
The clip length in seconds, as a whole number. All tasks. The minimum is 4. A longer clip uses more video tokens.
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. Treat it as an opaque string. 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 clip length in seconds.
string
The output aspect ratio, such as 16:9.
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
To guide the clip with references instead, give each reference item a 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 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
ByteDance also applies these limits to the content of a request:
  • 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.
  • duration is 4 seconds or more.
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.