Use AiLink to generate videos with Doubao Seedance, including text-to-video, first-frame image-to-video, and reference-video generation. Generation is asynchronous: create a task, poll its ID, and download the result when it is ready.
Before you start:
https://ailink.nativex.comAuthorization: Bearer sk-xxxx in the request headers. Replace sk-xxxx with your API Key.application/json1. Create a video generation task
Request
POST/doubao/api/v3/contents/generations/tasksBody parameters:
| Parameter | Type | Required | Description and values |
|---|---|---|---|
model |
string | Yes | Model name configured in the gateway; see the model specifications below |
content |
object[] | Yes | Input items containing text and any media; see the item fields below |
resolution |
string | No | Output resolution: 480p, 720p, 1080p, or 4k, depending on the model. Ark defaults to 720p. Set this explicitly. |
ratio |
string | No | 16:9, 4:3, 1:1, 3:4, 9:16, 21:9, or adaptive. Default: adaptive, which lets the model choose an appropriate aspect ratio. |
duration |
integer | No | Output length in seconds: 4–30 for 2.5, or 4–15 for the 2.0 series. Ark also accepts -1 for automatic selection; 2.5 defaults to -1. These examples explicitly request 5 seconds. |
generate_audio |
boolean | No | true generates audio; false produces a silent video. Default: true. |
watermark |
boolean | No | true adds a watermark; false omits it. Default: false. |
return_last_frame |
boolean | No | Default: false. Set to true to obtain the generated video's last-frame image in the task result. |
output_format |
string | No | 2.5 only: mp4 or mov. Default: mp4. |
omni_reference_task_type |
string | No | 2.5 multimodal reference tasks only: auto (default), reference, edit, or extend. The corresponding task restrictions apply. |
Model specifications:
| Model | Output resolutions | Explicit output duration |
|---|---|---|
doubao-seedance-2-5-260628 |
480p / 720p / 1080p |
4–30 seconds |
doubao-seedance-2-0-260128 |
480p / 720p / 1080p / 4k |
4–15 seconds |
doubao-seedance-2-0-fast-260128 |
480p / 720p |
4–15 seconds |
doubao-seedance-2-0-mini-260615 |
480p / 720p |
4–15 seconds |
content item fields:
| Field | Type | Description and values |
|---|---|---|
type |
string | text for a prompt, image_url for an image, video_url for a video, or audio_url for reference audio |
text |
string | Required for type=text; describes the desired video |
image_url.url |
string | Required for type=image_url; these examples use a publicly accessible image URL |
video_url.url |
string | Required for type=video_url; use a publicly accessible video URL. Base64 video input is not supported. |
audio_url.url |
string | Required for type=audio_url; a publicly accessible audio URL can be used |
role |
string | Images: first_frame, last_frame, or reference_image. Videos: reference_video. Audio: reference_audio. |
first_frame / last_frame with reference images, videos, or audio. The 2.0 series requires reference audio to be accompanied by a reference image or video; 2.5 supports audio-only reference input.Response
Successful response example:
{"id": "task_xxxxxxxx"}
| Field | Type | Description |
|---|---|---|
id |
string | Generation task ID; use this value to query the task |
Example
This request generates a silent, 5-second video at 480p:
curl -X POST 'https://ailink.nativex.com/doubao/api/v3/contents/generations/tasks' \
-H 'Authorization: Bearer sk-xxxx' \
-H 'Content-Type: application/json' \
-d '{
"model": "doubao-seedance-2-0-mini-260615",
"content": [
{"type": "text", "text": "An orange cat walks slowly across a grassy field"}
],
"resolution": "480p",
"ratio": "16:9",
"duration": 5,
"generate_audio": false,
"watermark": false
}'
2. Query the video generation result
Request
GET/doubao/api/v3/contents/generations/tasks/{task_id}| Path parameter | Type | Required | Description |
|---|---|---|---|
task_id |
string | Yes | The id returned when the task was created |
No request body is needed. Generation usually takes a few minutes. Poll approximately every 10 seconds until the task reaches a terminal state.
Response
The following is a simplified successful result. The video URL and usage value are illustrative:
{
"id": "task_xxxxxxxx",
"status": "succeeded",
"content": {
"video_url": "https://example.com/generated-video.mp4"
},
"usage": {
"total_tokens": 100000
}
}
Response fields:
| Field | Type | Description |
|---|---|---|
id |
string | Task ID |
status |
string | Current task state; see below |
content.video_url |
string | Video download URL returned on success |
content.last_frame_url |
string | Last-frame image URL when return_last_frame=true was requested |
usage.total_tokens |
integer | Actual token usage for the task; use the returned value |
error |
object | Error details returned on failure |
Task states:
| Status | Meaning | Next action |
|---|---|---|
queued |
Waiting in the queue | Wait, then query again |
running |
Generation in progress | Wait, then query again |
succeeded |
Completed successfully | Download the video and stop polling |
failed |
Failed | Read the error details and stop polling |
cancelled |
Cancelled | Stop polling |
expired |
Timed out | Stop polling |
Example
Replace task_xxxxxxxx with the actual task ID:
curl 'https://ailink.nativex.com/doubao/api/v3/contents/generations/tasks/task_xxxxxxxx' \
-H 'Authorization: Bearer sk-xxxx'
3.View progress and generated videos in the console
Video generation requests run as asynchronous tasks. After submitting a task, open the gateway Console → Task Logs to check its generation progress. Once generation succeeds, click Artifacts for the task to view and download the generated video.

4.First-frame image-to-video
Use the same creation endpoint and query workflow. Keep the text prompt and replace content with the following array. Replace the image URL with your own media URL:
[
{"type": "text", "text": "Make the subject in the image move slowly forward"},
{
"type": "image_url",
"image_url": {"url": "https://example.com/first.png"},
"role": "first_frame"
}
]
To specify a final frame, add another image with role=last_frame alongside the first-frame image.
ratio=adaptive for first-frame or first-and-last-frame generation. Change 16:9 in the text-to-video example to adaptive; the model will preserve the first-frame image's aspect ratio.5. Reference-video generation
Use the same creation endpoint and query workflow. Replace content with the following array and substitute your own video URL:
[
{"type": "text", "text": "Use the motion in the reference video to generate a new video of an orange cat walking slowly across a grassy field"},
{
"type": "video_url",
"video_url": {"url": "https://example.com/ref.mp4"},
"role": "reference_video"
}
]
For Seedance 2.5, omni_reference_task_type=reference can guide reference generation. The prompt should express the intention to create new content using the reference media.
ratio=adaptive, duration=-1, and a reference video lasting 4–30 seconds. Video extension requires ratio=adaptive. A task can still fail asynchronously if its inferred intent conflicts with the parameters, so continue checking its status after submission.Media requirements
| Media | Requirements |
|---|---|
| Images | Less than 30 MB each; width and height each 300–6000 pixels; aspect ratio 0.4–2.5. Use one image for a first frame or two for first and last frames. |
| Reference videos | mp4 or mov; no more than 200 MB each; 24–60 FPS; width and height each 300–6000 pixels; aspect ratio 0.4–2.5; total pixel count 407696–8295044. |
| 2.5 reference video duration | Normally 2–30 seconds per video; 4–30 seconds for editing. Up to 10 videos, with a combined duration of no more than 30 seconds. |
| 2.0 series reference video duration | 2–15 seconds per video. Up to 3 videos, with a combined duration of no more than 15 seconds. |
These examples use publicly accessible media URLs. Ark also accepts Base64 images; Base64 video input is not supported. Input media duration and the output length specified by duration are separate parameters.
For additional parameters and the latest model restrictions, refer to the official Ark API documentation.