创建 Seedance 视频生成任务

创建接口是异步接口。请求被接受后先返回任务 ID，视频生成完成后再通过查询接口取得下载地址。

请求

POST https://video.pinducloud.com.cn/doubao/api/v3/contents/generations/tasks

curl --request POST "$BASE_URL/doubao/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "一只纸飞机穿过城市上空，镜头跟随它飞过屋顶"}
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": false,
    "watermark": false,
    "output_format": "mp4"
  }'

顶层字段

字段	类型	必填	取值或范围	说明
model	string	是	已开放的 Seedance 模型 ID	选择模型和对应计费规则
content	array	是	文本、图片、视频、音频或 Draft 项	描述生成内容及参考素材
resolution	string	否	2.0 标准版：`480p`、`720p`、`1080p`、`4k`；Fast/Mini：`480p`、`720p`；2.5：`480p`、`720p`、`1080p`	未传时 Fast/Mini 按 `720p` 预估，标准版和 2.5 按 `1080p` 预估；不保证实际输出采用预估分辨率
ratio	string	否	16:9、4:3、1:1、3:4、9:16、21:9、adaptive	输出画面比例
duration	integer	否	三个 2.0 模型为 `-1` 或 4~~15；2.5 入口接受 `-1` 或 4~~30	单位为秒；`-1` 请求智能时长，实际结果由模型返回
frames	integer	否	三个 2.0 模型的本站入口不接受	这是本站入口限制，不代表其他 Seedance 版本都不支持
callback_url	string	否	HTTP/HTTPS 公网地址	接收模型服务的状态通知；受理成功不保证回调可达
return_last_frame	boolean	否	true / false	成功时是否返回尾帧地址，默认 false
service_tier	string	否	三个 2.0 模型的本站入口不接受	`default`/`flex` 仅用于列表过滤，其他模型以对应接口为准
execution_expires_after	integer	否	3600~259200	从创建时间起的过期秒数，默认 172800
generate_audio	boolean	否	true / false	`false` 用于请求无声视频；实际音频以生成结果为准
draft	boolean	否	三个 2.0 模型的本站入口不接受 `true`	Draft 流程只适用于相应的其他模型
tools	array	否	当前入口接受 `[{"type":"web_search"}]`	是否实际执行以任务结果为准
safety_identifier	string	否	ASCII 字符串，最长 64 字符	终端用户稳定标识
priority	integer	否	0~9	系统校验范围并传递；实际调度效果以任务结果为准
seed	integer	否	-1~2^32-1	控制随机性，默认 -1
camera_fixed	boolean	否	三个 2.0 模型的本站入口不接受	标准版不支持，本站对三个模型提前返回 400
output_format	string	否	三个 2.0 模型只接受 `mp4`	标准版不支持 `mov`，本站提前返回 400
omni_reference_task_type	string	否	仅在对应模型明确支持时使用	当前入口可传递；不能据此推断 2.0 已启用该能力
watermark	boolean	否	true / false	是否添加右下角 AIGC 水印

时长与帧数

对当前三个 Seedance 2.0 模型，使用 duration 指定整数秒；duration: -1 表示智能时长。本站入口不接受这三个模型的 frames 字段，因此不能用 frames 绕过 4~15 秒限制。其他模型的帧数能力不在本页的 2.0 规则内，应按其对应接口调用说明：

模型系列	duration
Seedance 2.0 标准版/Fast/Mini	4~15 秒，或 `-1`
Seedance 2.5	本站入口接受 4~30 秒，或 `-1`；实际可生成时长以模型处理结果为准
其他 Seedance 模型	以对应模型能力为准，不套用 2.0 的范围

系统会拒绝非整数和明显越界的时长；即使通过本站检查，模型服务仍可能因不支持某个时长而返回 400。

content 项

每一项通过 type 指明内容种类。content 至少包含一个非空文本或媒体项，文本项可以放在媒体项之前或之后；数组中的文本和媒体顺序会保留。

type	主要字段	role	用途
text	text	无	视频提示词
image_url	image_url.url	`first_frame`、`last_frame` 或 `reference_image`	单张图片可省略 role，默认作为首帧；多张图片必须写 role
video_url	video_url.url	`reference_video`	参考视频，2.0 系列支持
audio_url	audio_url.url	`reference_audio`	参考音频，2.0 系列支持
draft_task	draft_task.id	无	使用已有 Draft 任务生成正式视频

媒体 URL 可以是公网地址、符合接口要求的 Base64 data URI，或已登记的素材引用。私域素材库素材使用 asset://<AssetId> 引用，其中 <AssetId> 是素材列表返回的 asset_id。接口不接受本地文件路径和 multipart 上传。

本地文件请先使用 API Key 调用 /v1/seedance/assets/upload 上传。同一用户的有效 API Key 共享素材库，完整参数及流程见私域素材库。

例如，使用私域素材库中的图片作为参考图：

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "asset://asset-xxxxxxxx"
  }
}

不要把不带 asset:// 前缀的 asset_id 当作 URL。有效且模型服务可访问的 preview_url 可以作为普通公网媒体地址提交，媒体类型、格式和角色仍需满足所选模型的输入要求。临时地址可能在排队或读取前过期，长期复用应优先保存 asset_id 并使用 asset://<AssetId>，不要依赖旧预览地址。

回调与状态同步

callback_url 用于接收模型服务发送的异步状态通知。创建接口不以回调地址的可达性作为受理前提，返回任务 ID 不表示回调地址验证成功或通知已送达。接收端必须公网可达；通知投递失败时，客户端仍应通过任务查询接口获取结果。

通知可能重复或乱序到达。接收端应按任务标识归并状态，对重复事件进行幂等处理，不要让 queued 覆盖已保存的 running，也不要让非终态覆盖已保存的终态。最终结果通过查询任务确认，并保留回调丢失时的轮询处理。

回调载荷的任务标识不保证与创建响应中的公开 task_... ID 相同。保存创建响应的 id，后续查询始终使用该 ID；不要直接把回调中的标识当作本站查询路径参数。真人认证中的同名 callback_url 是浏览器回跳地址，与视频任务状态通知不同。

输入约束

以下媒体规格用于 2.0 系列接入参考。本站会检查内容结构、角色、数量和参数类型；外部文件的编码、尺寸、帧率及内容审核由模型服务继续检查，通过请求校验不等于生成成功。 2.5 的输入规格与能力不能直接由此推断，未确认的组合以模型处理结果为准。

图片

JPEG、PNG、WEBP、BMP、TIFF、GIF；1.5 pro 和 2.0 系列另支持 HEIC、HEIF。
单张小于 30 MB，宽高均需在 300~6000 像素之间。
宽高比需在 (0.4, 2.5) 范围内。
首尾帧各最多一张；2.0 多模态参考图片最多 9 张。

视频

Seedance 2.0 系列参考视频使用 MP4 或 MOV 容器。
视频编码支持 H.264/AVC、H.265/HEVC；音频支持 AAC、MP3。
单个视频 2~~15 秒、24~~60 FPS、大小不超过 50 MB，最多 3 个。
所有参考视频总时长不超过 15 秒，宽高比为 [0.4, 2.5]，宽高为 300~6000 像素。

音频

Seedance 2.0 系列参考音频使用 WAV 或 MP3 格式。
单段音频 2~15 秒、大小不超过 15 MB，最多 3 段，总时长不超过 15 秒。
音频不能单独出现，至少还要提供一张参考图或一个参考视频。

常用场景

首帧图生视频

curl --request POST "$BASE_URL/doubao/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-0-fast-260128",
    "content": [
      {"type": "text", "text": "镜头缓慢推近，湖面出现自然的涟漪"},
      {
        "type": "image_url",
        "image_url": {"url": "https://cdn.example.com/lake-start.jpg"},
        "role": "first_frame"
      }
    ],
    "resolution": "720p",
    "ratio": "adaptive",
    "duration": 5
  }'

首尾帧图生视频

curl --request POST "$BASE_URL/doubao/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {"type": "text", "text": "让天空从深蓝自然过渡到日出后的橙红色"},
      {
        "type": "image_url",
        "image_url": {"url": "https://cdn.example.com/sunrise-start.jpg"},
        "role": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": {"url": "https://cdn.example.com/sunrise-end.jpg"},
        "role": "last_frame"
      }
    ],
    "resolution": "720p",
    "duration": 8
  }'

多模态参考

2.0 系列可以把图片、视频和音频作为参考输入。提示词中用“图片 1”“视频 1” 等序号指代对应素材，顺序按各类素材在 content 中的出现顺序计算。参考媒体必须使用 reference_image、reference_video 或 reference_audio 角色。

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "参考图片 1 的角色在参考视频 1 的动作基础上说话"},
    {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://cdn.example.com/character.png"}},
    {"type": "video_url", "role": "reference_video", "video_url": {"url": "https://cdn.example.com/motion.mp4"}},
    {"type": "audio_url", "role": "reference_audio", "audio_url": {"url": "https://cdn.example.com/voice.mp3"}}
  ],
  "resolution": "720p",
  "duration": 6,
  "generate_audio": true
}

Draft 转正式视频

先使用 draft: true 创建支持 Draft 的模型样片任务；当前三个 2.0 模型不接受 draft: true，但允许传 draft: false。
查询样片并确认结果。
将样片任务 ID 放入新的 draft_task.id，创建正式任务。

样片请求须使用 480p，不能同时启用 return_last_frame: true 或 service_tier: "flex"。正式请求中的 draft_task 必须是 content 唯一一项，不能再混入文本、图片、视频或音频。下面示例仅适用于已开通 Draft 能力的模型。

{
  "model": "doubao-seedance-1-5-pro-251215",
  "content": [
    {"type": "draft_task", "draft_task": {"id": "task_gateway_draft_01"}}
  ],
  "resolution": "720p",
  "duration": 8,
  "draft": false
}

提交时使用公开任务 ID，系统会校验任务归属并处理 Draft 关联。该流程不能用于当前三个 Seedance 2.0 模型。

成功响应

{
  "id": "task_gateway_doubao_01"
}

id 用于后续查询、列表过滤和取消/删除。首次查询应在创建后等待约 10 秒。

失败处理

本站明确拒绝的字段、参数类型、模型分辨率和媒体结构错误会在任务创建前返回 400，不会产生已创建的任务。其他参数可能在任务处理时继续校验；任务已经创建但生成失败时，查询接口返回 status: "failed" 和 error。创建成功只表示任务已受理。

使用已认证真人时，先按真人认证与人像素材完成认证和人像上传，再以 image_url / reference_image 引用审核通过的 asset_id。普通建组不能通过传入 GroupType: "LivenessFace" 跳过认证。

若收到 409 private_asset_mapping_pending，素材仍在准备，按 Retry-After 等待后再尝试；这次响应没有返回任务 ID，不代表已创建视频。网络超时则应先查询任务列表，避免把已成功受理的创建请求重复发送。计费和退款规则见查询任务。

请求​

顶层字段​

时长与帧数​

content 项​

回调与状态同步​

输入约束​

图片​

视频​

音频​

常用场景​

首帧图生视频​

首尾帧图生视频​

多模态参考​

Draft 转正式视频​

成功响应​

失败处理​

请求