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/generationsRequest body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | yes | A model id from GET /models |
prompt | string | yes* | What to generate. *Optional only for tools that work on media alone |
scene | string | no | One of the model's scenes. Defaults to the first |
options | object | no | Model options: duration, resolution, aspect ratio and media inputs (see below) |
Options
| Option | Type | Used by | Description |
|---|---|---|---|
duration | string | video | Output length in seconds, e.g. "5". See parameters.durations |
resolution | string | video | "480p", "720p", "1080p"… See parameters.resolutions |
aspect_ratio | string | video, image | "16:9", "9:16", "1:1"… See parameters.aspect_ratios |
generate_audio | boolean | video with has_audio | Generate a soundtrack. Defaults to the model's website default |
image_urls | string[] | image-to-video, reference | Public image URLs. For image-to-video the first is the first frame |
video_urls | string[] | reference-to-video | Public reference video URLs |
audio_urls | string[] | reference-to-video | Public reference audio URLs |
video_url | string | video-to-video, video tools | Source 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
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" }
}'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"
}
}'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
}| Field | Description |
|---|---|
id | Generation id. Use it to poll |
status | pending, processing, success, failed or canceled |
model | The model id you requested |
model_name | Display name of the model |
media_type | video, image or music |
outputs | Result 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.