Search...
Menu

Seedance Video Generation Guide

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:

•Gateway URL: https://ailink.nativex.com
•Authentication: Include Authorization: Bearer sk-xxxx in the request headers. Replace sk-xxxx with your API Key.
•Content type: application/json

1. Create a video generation task

Request

•Method: POST
•Path: /doubao/api/v3/contents/generations/tasks

Body 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.
Values and model restrictions follow the Ark Create Video Generation Task documentation. Defaults refer to Ark model defaults. First-frame, first-and-last-frame, and multimodal reference inputs are mutually exclusive: do not mix 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

•Method: GET
•Path: /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.

Tip: Generated video URLs are available for only 24 hours. They become inaccessible after expiration, so download and save your videos promptly after generation.

 

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.

Seedance 2.5 requires 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.

Video editing with 2.5 requires 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.

Last modified: 2026-11-17