Back to Details

seedance-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Seedance 2.0 API

Seedance 2.0 API

Seedance 2.0 is an AI video generation model on the Volcengine Ark platform. It supports text-to-video, image-to-video, multimodal reference, video editing, video extension, and audio-synced video generation. This skill covers direct API usage (curl, Python SDK, etc.) without any custom CLI wrapper.
Seedance 2.0是火山引擎Ark平台上的AI视频生成模型，支持文生视频、图生视频、多模态参考、视频编辑、视频延展、音画同步视频生成。本技能涵盖直接使用API（curl、Python SDK等）的方法，不包含任何自定义CLI封装。

Models

可用模型

ModelModel IDBest for
Seedance 2.0
doubao-seedance-2-0-260128
Highest quality
Seedance 2.0 fast
doubao-seedance-2-0-fast-260128
Faster/cheaper, same capabilities
Both models share the same capabilities. Use 2.0 for maximum quality, 2.0 fast when speed and cost matter more.
模型模型ID适用场景
Seedance 2.0
doubao-seedance-2-0-260128
最高生成质量
Seedance 2.0 快速版
doubao-seedance-2-0-fast-260128
更快/更低成本，功能与标准版完全一致
两个版本的功能完全相同。追求最高质量请使用2.0标准版，优先考虑速度和成本时请使用2.0快速版。

Authentication

身份认证

The API uses an API Key via the 
ARK_API_KEY
environment variable. Pass it as a Bearer token:
Authorization: Bearer $ARK_API_KEY
The user is responsible for obtaining and configuring their own API key from the Volcengine Ark console. Never hardcode or generate credentials.
API通过
ARK_API_KEY
环境变量读取API Key，需要将其作为Bearer令牌传递：
Authorization: Bearer $ARK_API_KEY
用户需要自行从火山引擎Ark控制台获取并配置自己的API Key，严禁硬编码或生成凭证。

Core Workflow

核心工作流

Video generation is asynchronous — a two-step process:
  1. Create a task via 
    POST /contents/generations/tasks
    — returns a task ID
  2. Poll the task via 
    GET /contents/generations/tasks/{id}
    — until 
    status
    is 
    succeeded
    or 
    failed
  3. When succeeded, the response contains 
    content.video_url
    with the MP4 download link (valid for 24h)
视频生成是异步流程，分为两个核心步骤：
  1. 通过
    POST /contents/generations/tasks
    创建任务 —— 返回任务ID
  2. 通过
    GET /contents/generations/tasks/{id}
    轮询任务状态 —— 直到
    status
    变为
    succeeded
    或
    failed
  3. 任务成功后，响应中会包含
    content.video_url
    字段，提供MP4下载链接（有效期24小时）

API Base URL

API 基础地址

https://ark.cn-beijing.volces.com/api/v3
https://ark.cn-beijing.volces.com/api/v3

Endpoints

接口列表

MethodPathPurpose
POST
/contents/generations/tasks
Create a video generation task
GET
/contents/generations/tasks/{id}
Get task status and result
GET
/contents/generations/tasks
List tasks with filters
DELETE
/contents/generations/tasks/{id}
Cancel queued / delete completed task
请求方法路径用途
POST
/contents/generations/tasks
创建视频生成任务
GET
/contents/generations/tasks/{id}
获取任务状态和结果
GET
/contents/generations/tasks
按筛选条件列出任务
DELETE
/contents/generations/tasks/{id}
取消排队中任务/删除已完成任务

Generation Modes

生成模式

Seedance 2.0 supports these input combinations (all via the 
content
array):
Seedance 2.0支持以下输入组合（所有输入均通过
content
数组传递）：

Text-to-Video

文生视频

Just a text prompt — the simplest mode.
仅输入文本提示词，是最简单的生成模式。

Image-to-Video (First Frame)

图生视频（指定首帧）

One image + optional text. The image becomes the video's first frame.
  • Set image 
    role
    to 
    first_frame
    (or omit — it defaults to first frame with a single image)
输入1张图片+可选文本，图片将作为视频的首帧。
  • 将图片的
    role
    设置为
    first_frame
    （如果只传入1张图片可以省略该参数，默认会作为首帧使用）

Image-to-Video (First + Last Frame)

图生视频（指定首尾帧）

Two images + optional text. Control both start and end frames.
  • First image: 
    role: "first_frame"
  • Second image: 
    role: "last_frame"
输入2张图片+可选文本，可同时控制视频的起始和结束帧。
  • 第一张图片：
    role: "first_frame"
  • 第二张图片：
    role: "last_frame"

Multimodal Reference

多模态参考

The most powerful mode — combine images (0-9), videos (0-3), audio (0-3), and text.
  • Images use 
    role: "reference_image"
  • Videos use 
    role: "reference_video"
  • Audio uses 
    role: "reference_audio"
  • Audio cannot be the sole input; at least one image or video is required alongside it
功能最强大的模式，可组合使用图片（0-9张）、视频（0-3个）、音频（0-3个）和文本。
  • 图片使用
    role: "reference_image"
  • 视频使用
    role: "reference_video"
  • 音频使用
    role: "reference_audio"
  • 音频不能作为唯一输入，必须同时搭配至少1张图片或1个视频使用

Video Editing

视频编辑

Provide a reference video + text describing the edits (e.g., "replace the perfume with a cream jar").
提供参考视频+描述编辑需求的文本（例如："把香水换成面霜罐"）。

Video Extension

视频延展

Provide 1-3 reference videos + text describing how to extend or stitch them.
提供1-3个参考视频+描述延展或拼接方式的文本。

Content Array Types

Content 数组类型说明

Each item in the 
content
array has a 
type
and corresponding payload:
Text:
json
{ "type": "text", "text": "your prompt here" }
Image:
json
{
  "type": "image_url",
  "image_url": { "url": "<URL, base64, or asset://ID>" },
  "role": "first_frame | last_frame | reference_image"
}
Video:
json
{
  "type": "video_url",
  "video_url": { "url": "<URL or asset://ID>" },
  "role": "reference_video"
}
Audio:
json
{
  "type": "audio_url",
  "audio_url": { "url": "<URL, base64, or asset://ID>" },
  "role": "reference_audio"
}
content
数组中的每个条目都有
type
字段和对应的载荷：
文本：
json
{ "type": "text", "text": "你的提示词在此处" }
图片：
json
{
  "type": "image_url",
  "image_url": { "url": "<URL、base64编码内容或asset://ID>" },
  "role": "first_frame | last_frame | reference_image"
}
视频：
json
{
  "type": "video_url",
  "video_url": { "url": "<URL或asset://ID>" },
  "role": "reference_video"
}
音频：
json
{
  "type": "audio_url",
  "audio_url": { "url": "<URL、base64编码内容或asset://ID>" },
  "role": "reference_audio"
}

Request Parameters

请求参数说明

ParameterTypeDefaultNotes
model
stringrequiredModel ID (see table above)
content
arrayrequiredArray of text/image/video/audio objects
ratio
string
"adaptive"
16:9
, 
4:3
, 
1:1
, 
3:4
, 
9:16
, 
21:9
, 
adaptive
duration
integer
5
Video length in seconds. Range: [4, 15]. Use 
-1
for auto.
resolution
string
"720p"
480p
or 
720p
(1080p not supported for 2.0)
generate_audio
boolean
true
Whether to generate synced audio
watermark
boolean
false
Include watermark
seed
integer
-1
Reproducibility seed. [-1, 2^32-1]
return_last_frame
boolean
false
Return the last frame as PNG (useful for chaining)
callback_url
string-Webhook URL for status notifications
tools
array-
[{"type": "web_search"}]
to enable web search (text-only)
execution_expires_after
integer
172800
Task timeout in seconds [3600, 259200]
safety_identifier
string-End-user identifier for abuse monitoring
参数名类型默认值说明
model
string必填模型ID（参考上方模型表格）
content
array必填文本/图片/视频/音频对象组成的数组
ratio
string
"adaptive"
可选值：
16:9
、
4:3
、
1:1
、
3:4
、
9:16
、
21:9
、
adaptive
（自适应）
duration
integer
5
视频时长，单位秒，取值范围：[4, 15]，传
-1
表示自动计算
resolution
string
"720p"
可选值：
480p
或
720p
（2.0版本暂不支持1080p）
generate_audio
boolean
true
是否生成同步音频
watermark
boolean
false
是否添加水印
seed
integer
-1
可复现随机种子，取值范围：[-1, 2^32-1]
return_last_frame
boolean
false
是否返回最后一帧PNG图片（用于多段视频拼接场景）
callback_url
string-接收状态通知的Webhook地址
tools
array-传
[{"type": "web_search"}]
可启用联网搜索（仅纯文本输入场景支持）
execution_expires_after
integer
172800
任务超时时间，单位秒，取值范围：[3600, 259200]
safety_identifier
string-终端用户标识，用于滥用行为监控

Task Statuses

任务状态说明

StatusMeaning
queued
Waiting in queue
running
Generation in progress
succeeded
Done — 
content.video_url
available
failed
Error — check 
error.code
and 
error.message
cancelled
Task was cancelled while queued
expired
Task exceeded timeout
状态含义
queued
排队中
running
生成中
succeeded
生成成功 —— 可获取
content.video_url
failed
生成失败 —— 可查看
error.code
和
error.message
获取错误信息
cancelled
任务已在排队阶段被取消
expired
任务执行超时

Examples

使用示例

curl — Text-to-Video

curl — 文生视频

bash
undefined
bash
undefined

Step 1: Create task

步骤1：创建任务

curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
-H "Content-Type: application/json"
-H "Authorization: Bearer $ARK_API_KEY"
-d '{ "model": "doubao-seedance-2-0-260128", "content": [ { "type": "text", "text": "A cat yawning at the camera, soft lighting, close-up shot" } ], "generate_audio": true, "ratio": "16:9", "duration": 5, "watermark": false }'
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
-H "Content-Type: application/json"
-H "Authorization: Bearer $ARK_API_KEY"
-d '{ "model": "doubao-seedance-2-0-260128", "content": [ { "type": "text", "text": "A cat yawning at the camera, soft lighting, close-up shot" } ], "generate_audio": true, "ratio": "16:9", "duration": 5, "watermark": false }'

Step 2: Poll for result (replace TASK_ID)

步骤2：轮询获取结果（替换TASK_ID为实际任务ID）

curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/TASK_ID
-H "Content-Type: application/json"
-H "Authorization: Bearer $ARK_API_KEY"
undefined
curl -X GET https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/TASK_ID
-H "Content-Type: application/json"
-H "Authorization: Bearer $ARK_API_KEY"
undefined

curl — Image-to-Video (First Frame)

curl — 图生视频（指定首帧）

bash
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {
            "type": "text",
            "text": "The girl opens her eyes and looks at the camera gently"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/first-frame.png"
            }
        }
    ],
    "generate_audio": true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'
bash
curl -X POST https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
        {
            "type": "text",
            "text": "The girl opens her eyes and looks at the camera gently"
        },
        {
            "type": "image_url",
            "image_url": {
                "url": "https://example.com/first-frame.png"
            }
        }
    ],
    "generate_audio": true,
    "ratio": "adaptive",
    "duration": 5,
    "watermark": false
}'

Python SDK — Full Workflow with Polling

Python SDK — 带轮询的完整工作流

python
import os
import time
from volcenginesdkarkruntime import Ark
python
import os
import time
from volcenginesdkarkruntime import Ark

pip install 'volcengine-python-sdk[ark]'

安装依赖：pip install 'volcengine-python-sdk[ark]'

client = Ark( base_url="https://ark.cn-beijing.volces.com/api/v3", api_key=os.environ.get("ARK_API_KEY"), )
client = Ark( base_url="https://ark.cn-beijing.volces.com/api/v3", api_key=os.environ.get("ARK_API_KEY"), )

Create task

创建任务

result = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[ {"type": "text", "text": "A cat yawning at the camera"}, { "type": "image_url", "image_url": {"url": "https://example.com/cat.png"}, }, ], generate_audio=True, ratio="adaptive", duration=5, watermark=False, ) task_id = result.id print(f"Task created: {task_id}")
result = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[ {"type": "text", "text": "A cat yawning at the camera"}, { "type": "image_url", "image_url": {"url": "https://example.com/cat.png"}, }, ], generate_audio=True, ratio="adaptive", duration=5, watermark=False, ) task_id = result.id print(f"任务已创建：{task_id}")

Poll until done

轮询直到任务完成

while True: task = client.content_generation.tasks.get(task_id=task_id) if task.status == "succeeded": print(f"Video URL: {task.content.video_url}") break elif task.status == "failed": print(f"Failed: {task.error}") break else: print(f"Status: {task.status}, waiting...") time.sleep(30)
undefined
while True: task = client.content_generation.tasks.get(task_id=task_id) if task.status == "succeeded": print(f"视频地址：{task.content.video_url}") break elif task.status == "failed": print(f"生成失败：{task.error}") break else: print(f"当前状态：{task.status}，等待中...") time.sleep(30)
undefined

Python SDK — Multimodal Reference (images + video + audio)

Python SDK — 多模态参考（图片+视频+音频）

python
result = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "Use video 1's first-person perspective, use audio 1 as background music. A fruit tea commercial...",
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/tea1.jpg"},
            "role": "reference_image",
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/tea2.jpg"},
            "role": "reference_image",
        },
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/reference.mp4"},
            "role": "reference_video",
        },
        {
            "type": "audio_url",
            "audio_url": {"url": "https://example.com/bgm.mp3"},
            "role": "reference_audio",
        },
    ],
    generate_audio=True,
    ratio="16:9",
    duration=11,
    watermark=False,
)
python
result = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "Use video 1's first-person perspective, use audio 1 as background music. A fruit tea commercial...",
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/tea1.jpg"},
            "role": "reference_image",
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/tea2.jpg"},
            "role": "reference_image",
        },
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/reference.mp4"},
            "role": "reference_video",
        },
        {
            "type": "audio_url",
            "audio_url": {"url": "https://example.com/bgm.mp3"},
            "role": "reference_audio",
        },
    ],
    generate_audio=True,
    ratio="16:9",
    duration=11,
    watermark=False,
)

Python SDK — Video Extension

Python SDK — 视频延展

python
result = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "Extend video 1 forward, the car drives into a desert oasis"},
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/clip.mp4"},
            "role": "reference_video",
        },
    ],
    generate_audio=True,
    ratio="16:9",
    duration=8,
    watermark=False,
)
python
result = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "Extend video 1 forward, the car drives into a desert oasis"},
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/clip.mp4"},
            "role": "reference_video",
        },
    ],
    generate_audio=True,
    ratio="16:9",
    duration=8,
    watermark=False,
)

Chaining Videos with Last Frame

使用最后一帧拼接多段视频

To create continuous multi-segment videos, use 
return_last_frame=True
on each task, then feed the last frame as the next task's first frame:
python
undefined
要生成连续的多段视频，可以在每个任务中开启
return_last_frame=True
，然后将上一段的最后一帧作为下一段任务的首帧传入：
python
undefined

Task 1: generate first segment

任务1：生成第一段视频

result1 = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[{"type": "text", "text": "Scene 1 description..."}], return_last_frame=True, duration=5, )
result1 = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[{"type": "text", "text": "场景1描述..."}], return_last_frame=True, duration=5, )

... poll until succeeded ...

... 轮询直到任务成功 ...

task1 = client.content_generation.tasks.get(task_id=result1.id) last_frame_url = task1.content.last_frame_url
task1 = client.content_generation.tasks.get(task_id=result1.id) last_frame_url = task1.content.last_frame_url

Task 2: use last frame as first frame

任务2：使用上一段的最后一帧作为首帧

result2 = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[ {"type": "text", "text": "Scene 2 continues from where scene 1 left off..."}, { "type": "image_url", "image_url": {"url": last_frame_url}, "role": "first_frame", }, ], return_last_frame=True, duration=5, )
undefined
result2 = client.content_generation.tasks.create( model="doubao-seedance-2-0-260128", content=[ {"type": "text", "text": "场景2从场景1结束的位置继续..."}, { "type": "image_url", "image_url": {"url": last_frame_url}, "role": "first_frame", }, ], return_last_frame=True, duration=5, )
undefined

Prompt Tips

提示词编写技巧

Seedance 2.0 understands natural language deeply. Structure prompts with:
  • Subject + Action (required): who is doing what
  • Environment + Aesthetics (optional): background, lighting, style
  • Camera + Audio (optional): camera movement, sound effects
When referencing multiple inputs, use ordinal references: "image 1", "video 2", "audio 1" — these map to the order of same-type items in the 
content
array (1-indexed).
For better instruction following with multiple reference images, use the bracket format: 
[image 1] description of first image's role, [image 2] description of second image's role
.
To generate speech, put dialogue in quotes: 
The man says: "Hello, welcome!"
Seedance 2.0对自然语言的理解能力很强，建议按以下结构编写提示词：
  • 主体+动作（必填）：谁在做什么
  • 环境+美学风格（可选）：背景、光线、风格
  • 镜头+音频（可选）：镜头运动、音效
当引用多个输入时，使用序号指代："图片1"、"视频2"、"音频1"——序号与
content
数组中同类型条目的顺序对应（从1开始计数）。
如果使用多张参考图片，为了让模型更好地遵循指令，可以使用括号格式：
[图片1] 第一张图片的作用描述，[图片2] 第二张图片的作用描述
。
要生成语音，将对话内容放在引号中即可：
男人说："你好，欢迎！"

Input Constraints

输入限制

Images: jpeg/png/webp/bmp/tiff/gif. Aspect ratio 0.4-2.5. Size < 30MB. Dimensions 300-6000px per side.
Videos: mp4/mov. Duration 2-15s per clip, total across all clips <= 15s. Resolution 480p-720p. Size < 50MB. FPS 24-60.
Audio: wav/mp3. Duration 2-15s per clip, total <= 15s. Size < 15MB.
Text prompt: Chinese < 500 chars, English < 1000 words recommended.
图片： 支持jpeg/png/webp/bmp/tiff/gif格式，宽高比0.4-2.5，大小<30MB，单边尺寸300-6000px。
视频： 支持mp4/mov格式，单片段时长2-15s，所有片段总时长<=15s，分辨率480p-720p，大小<50MB，帧率24-60。
音频： 支持wav/mp3格式，单片段时长2-15s，总时长<=15s，大小<15MB。
文本提示词： 建议中文<500字，英文<1000词。

Important Notes

重要注意事项

  • Generated video URLs expire after 24 hours — download or transfer promptly
  • Task records are kept for 7 days only
  • Seedance 2.0 does not support real human faces in uploaded reference images/videos (use virtual avatars via 
    asset://
    IDs or re-use model-generated videos for re-creation)
  • Offline inference (
    service_tier: "flex"
    ) is not supported for 2.0 models
  • The 
    frames
    parameter is not supported for 2.0 models — use 
    duration
    instead
  • camera_fixed
    is not supported for 2.0 models
  • Web search (
    tools: [{"type": "web_search"}]
    ) only works with text-only input
  • 生成的视频URL有效期为24小时，请及时下载或转存
  • 任务记录仅保留7天
  • Seedance 2.0不支持上传的参考图片/视频中出现真实人脸（可通过
    asset://
    ID使用虚拟形象，或复用模型生成的视频进行二次创作）
  • 2.0版本模型不支持离线推理（
    service_tier: "flex"
    ）
  • 2.0版本模型不支持
    frames
    参数，请使用
    duration
    参数控制时长
  • 2.0版本模型不支持
    camera_fixed
    参数
  • 联网搜索功能（
    tools: [{"type": "web_search"}]
    ）仅支持纯文本输入场景

Listing and Managing Tasks

任务列表查询与管理

bash
undefined
bash
undefined

List recent tasks

查询最近的任务

curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page_num=1&page_size=10"
-H "Authorization: Bearer $ARK_API_KEY"
curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?page_num=1&page_size=10"
-H "Authorization: Bearer $ARK_API_KEY"

Filter by status

按状态筛选任务

curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?filter.status=succeeded"
-H "Authorization: Bearer $ARK_API_KEY"
curl -X GET "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks?filter.status=succeeded"
-H "Authorization: Bearer $ARK_API_KEY"

Delete a task

删除任务

curl -X DELETE "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/TASK_ID"
-H "Authorization: Bearer $ARK_API_KEY"
undefined
curl -X DELETE "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/TASK_ID"
-H "Authorization: Bearer $ARK_API_KEY"
undefined

Further Reference

更多参考资料

This skill includes detailed reference files for deeper dives. Read them as needed:
  • references/api-reference.md
     — Condensed endpoint specs, request/response schemas, and status codes
  • references/input-specs.md
     — Exact constraints for images, videos, audio, text, and output resolution tables
  • references/examples.md
     — Ready-to-use code recipes for every generation mode (text-to-video, first frame, multimodal, editing, extension, chaining, virtual avatars, polling)
  • references/prompt-tips.md
     — Advanced prompt techniques: text overlays, subtitles, speech bubbles, multi-angle character reference, camera/audio reference patterns
本技能包含详细的参考文档，可按需查阅：
  • references/api-reference.md
     —— 精简版接口规范、请求/响应结构、状态码说明
  • references/input-specs.md
     —— 图片、视频、音频、文本的精确约束，以及输出分辨率对照表
  • references/examples.md
     —— 所有生成模式的开箱即用代码示例（文生视频、指定首帧、多模态、编辑、延展、拼接、虚拟形象、轮询）
  • references/prompt-tips.md
     —— 高级提示词技巧：文字叠加、字幕、对话气泡、多角度人物参考、镜头/音频参考模式