SeeDance 2.0 Video API Documentation

ByteDance Doubao SeeDance 2.0 provides high-quality video generation models. This document describes the complete API interface specification for using SeeDance 2.0 models for video generation. All video generation calls use the same /v1/video/generations endpoint, with different parameters depending on the use case.

Supported Models

Currently supported models include:

Model	Description
doubao-seedance-2-0-fast-260128	SeeDance 2.0 fast video generation model
doubao-seedance-2-0-260128	SeeDance 2.0 video generation model
dreamina-seedance-2-0-fast-260128	SeeDance 2.0 fast video generation model (overseas version)
dreamina-seedance-2-0-260128	SeeDance 2.0 video generation model (overseas version)

Overview

The SeeDance 2.0 video generation feature provides an asynchronous task processing mechanism:

Submit Task: Send an image and text prompt to create a video generation task
Query Status: Query generation progress and status through task ID
Get Results: Retrieve the generated video file after task completion

Task Status Flow

queued → in_progress → completed
                ↓
            failed

queued: Task has been submitted and is waiting to be processed
in_progress: Task is being processed
completed: Task completed successfully, video has been generated
failed: Task failed

API List

Method	Path	Description
POST	/v1/video/generations	Submit video generation task
GET	/v1/video/generations/{task_id}	Query task status

Usage Examples

1. Basic Text Prompt

Text-to-video uses prompt and model. Optional top-level fields include duration and size. Other options can go in metadata as needed.

Request body:

{
    "prompt": "A large hand-shaped marble statue with vines growing on it, on a platform in the middle of a shallow pool of water.",
    "model": "doubao-seedance-2-0-fast-260128",
    "duration": 8,
    "size": "720p",
    "metadata": {
        "ratio": "16:9",
        "callback_url": ""
    }
}

Field	Type	Required	Description
prompt	string	Yes	Text prompt for the video
model	string	Yes	Model name (e.g. `doubao-seedance-2-0-fast-260128`)
duration	integer	No	Default `5`. Allowed: integers from `4` to `15`, inclusive, or `-1` for automatic duration selection
size	string	No	Default `720p`. Allowed: `480p`, `720p`
metadata	object	No	Extra metadata
metadata.ratio	string	No	Default `adaptive`. Allowed: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
metadata.callback_url	string	No	If set, attempts to send callbacks to the specified URL. See Callback documentation for more details

2. First/Last Frame Images

Provide one or two image URLs in images: the first entry is the first frame; when two URLs are given, the second is the last frame. Optional top-level duration and size match Basic Text Prompt.

Request body:

{
    "prompt": "The girl in the frame says cheese to the camera; 360-degree orbit camera move.",
    "model": "doubao-seedance-2-0-fast-260128",
    "images": [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_first_frame.jpeg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_last_frame.jpeg"
    ],
    "duration": 8,
    "size": "720p",
    "metadata": {
        "ratio": "16:9",
        "callback_url": ""        
    }
}

Field	Type	Required	Description
prompt	string	Yes	Text prompt for the video
model	string	Yes	Model name (e.g. `doubao-seedance-2-0-fast-260128`)
images	array of string	Yes	One or two image URLs: first frame, and optionally last frame
duration	integer	No	Default `5`. Allowed: integers from `4` to `15`, inclusive, or `-1` for automatic duration selection
size	string	No	Default `720p`. Allowed: `480p`, `720p`
metadata	object	No	Extra metadata
metadata.ratio	string	No	Default `adaptive`. Allowed: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
metadata.callback_url	string	No	If set, attempts to send callbacks to the specified URL. See Callback documentation for more details

3. Reference Images

This flow also uses the top-level images array. Set metadata.imageMode to reference so each URL is treated as a reference image (not first/last frame). In this mode you can pass up to nine images. Optional top-level duration and size work the same as in Basic Text Prompt. In the prompt, reference images with tags such as [image 1], [image 2], … in the same order as images.

Request body:

{
    "prompt": "[image 1] A boy wearing glasses and a blue T-shirt and [image 2] a corgi puppy, sitting on the lawn in [image 3], 3D cartoon style.",
    "model": "doubao-seedance-2-0-fast-260128",
    "images": [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_ref_1.png",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_ref_2.png",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seelite_ref_3.png"
    ],
    "duration": 8,
    "size": "720p",
    "metadata": {
        "imageMode": "reference",
        "ratio": "16:9",
        "callback_url": ""
    }
}

Field	Type	Required	Description
prompt	string	Yes	Text prompt; use `[image 1]` … `[image N]` to refer to images in order
model	string	Yes	Model name (e.g. `doubao-seedance-2-0-fast-260128`)
images	array of string	Yes	Reference image URLs (up to 9 in this mode)
duration	integer	No	Default `5`. Allowed: integers from `4` to `15`, inclusive, or `-1` for automatic duration selection
size	string	No	Default `720p`. Allowed: `480p`, `720p`
metadata	object	No	Must include `imageMode`: `reference` for reference-image mode
metadata.imageMode	string	Yes (this mode)	Set to `reference`
metadata.ratio	string	No	Default `adaptive`. Allowed: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
metadata.callback_url	string	No	If set, attempts to send callbacks to the specified URL. See Callback documentation for more details

4. Reference Videos

Pass reference clip URLs in metadata.referenceVideos (up to three). The prompt can refer to them in order (e.g. [video 1], [video 2], [video 3]).

Request body:

{
    "prompt": "In [video 1], the arched window opens and we enter the gallery interior; cut to [video 2], then the camera moves into the painting; cut to [video 3].",
    "model": "doubao-seedance-2-0-fast-260128",
    "size": "720p",
    "duration": 8,
    "metadata": {
        "ratio": "16:9",
        "referenceVideos": [
            "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video1.mp4",
            "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video2.mp4",
            "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_extend_video3.mp4"
        ],
        "callback_url": ""
    }
}

Field	Type	Required	Description
prompt	string	Yes	Text prompt describing how to use the reference videos (e.g. `[video 1]`, `[video 2]`, `[video 3]` in order)
model	string	Yes	Model name (e.g. `doubao-seedance-2-0-fast-260128`)
duration	integer	No	Default `5`. Allowed: integers from `4` to `15`, inclusive, or `-1` for automatic duration selection
size	string	No	Default `720p`. Allowed: `480p`, `720p`
metadata	object	No	Must include `referenceVideos` for this mode
metadata.ratio	string	No	Default `adaptive`. Allowed: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
metadata.referenceVideos	array of string	Yes (this mode)	Up to 3 video URLs
metadata.callback_url	string	No	If set, attempts to send callbacks to the specified URL. See Callback documentation for more details

Constraints on each reference video (and inputs overall):

Count: at most 3 URLs in referenceVideos.
Container format: mp4 or mov.
Resolution: 480p or 720p.
Duration per clip: each video must be between 2 and 15 seconds (inclusive); combined duration of all input videos must not exceed 15 seconds.
Aspect ratio (width ÷ height): between 0.4 and 2.5 (inclusive).
Width and height (pixels): each between 300 and 6000 (inclusive).
Total pixels (width × height): between 409600 and 927408 (inclusive).
File size: each file must not exceed 50 MB.
Frame rate: between 24 and 60 fps (inclusive).

5. Multimodal References

Combine reference images (images + metadata.imageMode: reference), reference videos (metadata.referenceVideos), and reference audio (metadata.referenceAudio) in one request. Prompts can reference assets by role (e.g. [video 1], [audio 1], [image 1], [image 2]) as in the single-mode sections. Reference videos must still meet the constraints in Reference Videos.

Request body:

{
    "prompt": "First-person framing from [video 1] throughout; use [audio 1] as background music throughout. First-person fruit tea ad for Seedance Ping Ping An An limited-edition apple fruit tea. First frame is [image 1]: your hand picks a dewy Aksu red apple, crisp apple impact sounds. 2-4s: quick cuts — your hands drop apple pieces into a shaker with ice and tea base, shake hard; ice and shaker sounds sync to light drum hits; voiceover: Fresh-cut, shaken fresh. 4-6s: first-person product close-up — layered fruit tea poured into a clear cup, you pipe cream on top and apply a pink label wrap; camera pushes in on cream and tea layers. 6-8s: first-person — you raise the drink from [image 2] toward the camera (as if offering it to the viewer); label clearly visible; voiceover: Take a fresh sip; end frame freezes on [image 2]. Female voice throughout.",
    "model": "doubao-seedance-2-0-fast-260128",
    "images": [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg"
    ],
    "size": "720p",
    "duration": 11,
    "metadata": {
        "imageMode": "reference",
        "referenceVideos": [
            "https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"
        ],
        "referenceAudio": [
            "https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3"
        ],
        "ratio": "16:9",
        "callback_url": ""
    }
}

Field	Type	Required	Description
prompt	string	Yes	Long-form prompt referencing `[video N]`, `[audio N]`, `[image N]` as needed
model	string	Yes	Model name (e.g. `doubao-seedance-2-0-fast-260128`)
images	array of string	No	Reference image URLs when `metadata.imageMode` is `reference` (up to 9; see Reference Images)
duration	integer	No	Default `5`. Allowed: integers from `4` to `15`, inclusive, or `-1` for automatic duration selection
size	string	No	Default `720p`. Allowed: `480p`, `720p`
metadata	object	No	Combines modes below
metadata.imageMode	string	When using `images` as references	Set to `reference`
metadata.referenceVideos	array of string	No	Reference video URLs (up to 3; constraints in Reference Videos)
metadata.referenceAudio	array of string	No	Reference audio URLs
metadata.ratio	string	No	Default `adaptive`. Allowed: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`, `adaptive`
metadata.callback_url	string	No	If set, attempts to send callbacks to the specified URL. See Callback documentation for more details

1. Submit Video Generation Task

Use the JSON bodies in Usage Examples above; adjust fields for your scenario.

Complete Request:

curl -X POST "https://computevault.unodetech.xyz/v1/video/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d @request-body.json

Endpoint:

POST /v1/video/generations

Request Headers:

Parameter	Type	Required	Description
Content-Type	string	Yes	application/json
Authorization	string	Yes	Bearer API_KEY

Response Example:

{
  "task_id": "TASK_ID"
}

Response Field Descriptions:

Field	Type	Description
task_id	string	Task ID for subsequent task status queries

2. Query Task Status

Complete Request:

curl -X GET "https://computevault.unodetech.xyz/v1/video/generations/TASK_ID" \
  -H "Authorization: Bearer API_KEY"

Endpoint:

GET /v1/video/generations/{task_id}

Request Headers:

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer API_KEY

Path Parameters:

Parameter	Type	Required	Description
task_id	string	Yes	Task ID

Response Example (Processing):

{
    "code": "success",
    "message": "",
    "data": {
        "task_id": "<TASK_ID>",
        "action": "generate",
        "status": "IN_PROGRESS",
        "fail_reason": "",
        "submit_time": 1776717808,
        "start_time": 1776717809,
        "finish_time": 0,
        "progress": "30%",
        "data": {
            "created_at": 1776717808,
            "draft": false,
            "execution_expires_after": 172800,
            "generate_audio": true,
            "id": "<TASK_ID>",
            "model": "doubao-seedance-2-0-fast-260128",
            "service_tier": "default",
            "status": "running",
            "updated_at": 1776717808
        }
    }
}

Response Example (Success):

Note: When the task succeeds, the data.fail_reason field will contain the video download URL instead of an error message — this is a known behavior of the upstream SeeDance API. The recommended way to retrieve the video URL is via data.data.content.video_url.

{
    "code": "success",
    "message": "",
    "data": {
        "task_id": "<TASK_ID>",
        "action": "generate",
        "status": "SUCCESS",
        "fail_reason": "<VIDEO_URL>",
        "submit_time": 1776717808,
        "start_time": 1776717818,
        "finish_time": 1776717962,
        "progress": "100%",
        "data": {
            "content": {
                "video_url": "<VIDEO_URL>"
            },
            "created_at": 1776717808,
            "draft": false,
            "duration": 4,
            "execution_expires_after": 172800,
            "framespersecond": 24,
            "generate_audio": true,
            "id": "<TASK_ID>",
            "model": "doubao-seedance-2-0-fast-260128",
            "ratio": "16:9",
            "resolution": "480p",
            "seed": 93719,
            "service_tier": "default",
            "status": "succeeded",
            "updated_at": 1776717961,
            "usage": {
                "completion_tokens": 40594,
                "total_tokens": 40594
            }
        }
    }
}

3. Callback

POST <YOUR_CALLBACK_URL>

The webhook requests consist of "wrapper" data, taking the following format:

{
  "webhook_type": "VIDEO_TASK",
  "payload": {
    "channel_type": "DoubaoVideo",
    "data": {}
  }
}

The payload.data field contains the data in the same format that the 2. Query Task Status endpoint's response.data would provide.

Request Example (Task Running)

{
  "webhook_type": "VIDEO_TASK",
  "payload": {
    "channel_type": "DoubaoVideo",
    "data": {
      "task_id": "<TASK_ID>",
      "action": "generate",
      "status": "IN_PROGRESS",
      "fail_reason": "",
      "submit_time": 1776717808,
      "start_time": 1776717809,
      "finish_time": 0,
      "progress": "30%",
      "data": {
        "created_at": 1776717808,
        "draft": false,
        "execution_expires_after": 172800,
        "generate_audio": true,
        "id": "<TASK_ID>",
        "model": "doubao-seedance-2-0-fast-260128",
        "service_tier": "default",
        "status": "running",
        "updated_at": 1776717808
      }
    }
  }
}

Request Example (Task Completed Successfully)

{
  "webhook_type": "VIDEO_TASK",
  "payload": {
    "channel_type": "DoubaoVideo",
    "data": {
      "task_id": "<TASK_ID>",
      "action": "generate",
      "status": "SUCCESS",
      "fail_reason": "<VIDEO_URL>",
      "submit_time": 1776717808,
      "start_time": 1776717818,
      "finish_time": 1776717962,
      "progress": "100%",
      "data": {
        "content": {
          "video_url": "<VIDEO_URL>"
        },
        "created_at": 1776717808,
        "draft": false,
        "duration": 4,
        "execution_expires_after": 172800,
        "framespersecond": 24,
        "generate_audio": true,
        "id": "<TASK_ID>",
        "model": "doubao-seedance-2-0-fast-260128",
        "ratio": "16:9",
        "resolution": "480p",
        "seed": 93719,
        "service_tier": "default",
        "status": "succeeded",
        "updated_at": 1776717961,
        "usage": {
          "completion_tokens": 40594,
          "total_tokens": 40594
        }
      }
    }
  }
}

SeeDance 2.0 Video API Documentation

On this page