Generations

Create and poll video, image and music generations with the Seedance 3.0 API — request fields, options for each scene, and the generation object.

Create a generation

POST /api/v1/generations

Request body

FieldTypeRequiredDescription
modelstringyesA model id from GET /models
promptstringyes*What to generate. *Optional only for tools that work on media alone
scenestringnoOne of the model's scenes. Defaults to the first
optionsobjectnoModel options: duration, resolution, aspect ratio and media inputs (see below)

Options

OptionTypeUsed byDescription
durationstringvideoOutput length in seconds, e.g. "5". See parameters.durations
resolutionstringvideo"480p", "720p", "1080p"… See parameters.resolutions
aspect_ratiostringvideo, image"16:9", "9:16", "1:1"… See parameters.aspect_ratios
generate_audiobooleanvideo with has_audioGenerate a soundtrack. Defaults to the model's website default
image_urlsstring[]image-to-video, referencePublic image URLs. For image-to-video the first is the first frame
video_urlsstring[]reference-to-videoPublic reference video URLs
audio_urlsstring[]reference-to-videoPublic reference audio URLs
video_urlstringvideo-to-video, video toolsSource video to edit

Media inputs must be publicly reachable https:// URLs. Values outside a model's accepted list are normalised to the nearest supported value.

Examples

Text to video
curl https://seedance3ai.video/api/v1/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance25-text-to-video",
    "prompt": "Aerial shot of a lighthouse in a storm, waves crashing, moody light",
    "options": { "duration": "8", "resolution": "1080p", "aspect_ratio": "16:9" }
  }'
Image to video
curl https://seedance3ai.video/api/v1/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance25-image-to-video",
    "prompt": "The woman turns toward the camera and smiles, hair moving in the wind",
    "options": {
      "image_urls": ["https://example.com/portrait.jpg"],
      "duration": "5",
      "resolution": "720p"
    }
  }'
Reference to video
curl https://seedance3ai.video/api/v1/generations \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance25-reference-to-video",
    "prompt": "The character from image 1 walks through the city from video 1",
    "options": {
      "image_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/street.mp4"],
      "duration": "5"
    }
  }'

Response

201 Created with a generation object. Credits are deducted at this point.

Retrieve a generation

GET /api/v1/generations/{id}

Returns the current state of a generation. Each call also refreshes the status from the model provider, so polling this endpoint is all you need — no webhooks to set up.

curl https://seedance3ai.video/api/v1/generations/$GENERATION_ID \
  -H "Authorization: Bearer $SEEDANCE_API_KEY"

You can only read generations that belong to your account; any other id returns 404.

Polling

Poll every 5–10 seconds. Requests faster than about once per second for the same generation are rate limited with 429.

The generation object

{
  "id": "0b6f4c1e-8f1a-4d0e-9a51-1d3c2a7e9b10",
  "object": "generation",
  "status": "success",
  "model": "seedance25-text-to-video",
  "model_name": "Seedance 2.5",
  "media_type": "video",
  "scene": "text-to-video",
  "prompt": "Aerial shot of a lighthouse in a storm",
  "outputs": [
    {
      "type": "video",
      "url": "https://.../lighthouse.mp4",
      "thumbnail_url": "https://.../lighthouse.jpg"
    }
  ],
  "error": null
}
FieldDescription
idGeneration id. Use it to poll
statuspending, processing, success, failed or canceled
modelThe model id you requested
model_nameDisplay name of the model
media_typevideo, image or music
outputsResult files once status is success: type, url, optional thumbnail_url, duration
error{ "code", "message" } when status is failed, otherwise null

Download outputs you want to keep — result URLs are hosted by the model provider or our CDN and are not guaranteed to live forever.

Failed generations are refunded automatically, except when the finished output is blocked by content moderation or the job times out at the provider.