Skip to main content
POST
视频生成是异步任务。提交后接口会立即返回 task_id,可以通过 任务查询 轮询获取结果,也可以传入 callback_url 由上游主动推送结果(免轮询,见下文「回调通知」)。
本文档即 Seedance 官方用法(2.0 / 2.5)。promptsecondsimagesmetadata.* 等字段由平台转换为 ARK 上游请求体。模型价目与能力差异见 视频模型列表
超时重试 / 响应丢失:提交时建议带 Idempotency-Key(见下文);也可保存响应头 X-Oneapi-Request-Id,用 按 request_id 找回 查回 task_id。二者均约 24 小时有效,且不会重复预扣。

接口说明

通常需要 30-120 秒生成完成。建议每 5-8 秒轮询一次;传入 callback_url 时无需轮询。

文生视频

图生视频

基础模式传入 images 作为首帧或参考图片。
高级模式通过 metadata.content[] 指定首帧、尾帧、参考图/视频/音频,字段与豆包官方 content 一致。
使用 素材管理 登记的图片时,将 URL 换为 asset://asset-xxx(ID 格式以实际返回为准):

metadata.content 中的 role

若同时传 images[]metadata.content,平台以 metadata.content 为准images[] 不会保留)。

字段映射(服务端自动完成)

你只需按下方参数提交;平台转换为 ARK 上游 JSON:

回调通知(callback_url,免轮询)

提交任务时传入 callback_url,任务状态变化(排队 → 运行 → 成功/失败)时上游会主动向该地址 POST 推送任务结果,无需轮询。回调请求体的结构与 任务查询 接口的返回一致(含 idstatuscontent.video_urlusage 等字段),与豆包官方行为对齐。
  • 回调地址必须公网可达,并正常返回 2xx 响应。
  • 回调由上游直接发送到你的服务器,不经过平台转发;推送体中的 id 是上游任务 ID(cgt- 前缀),与本接口提交响应中的 task_id 是同一任务。如需校验真伪,可用提交响应的 task_id任务查询 交叉核对状态。
  • 回调与轮询可以混用,互不影响。

提交响应

请同时保存响应头中的 X-Oneapi-Request-Id(网关本次请求 ID)。若客户端超时未读到 body,可用该值做 按 request_id 找回

幂等提交(推荐)

客户端网络抖动或超时重试时,同一业务单号可能多次 POST。请在请求头携带稳定业务键: 重放成功时响应头含:
  • X-Idempotency-Replayed: true
  • X-Idempotency-Original-Request-Id:首次创建时的网关 request id(若有)
创建成功并已落库 task_id 的请求可被重放或找回。无 task_id 的失败响应不要当成排队成功;换键重试前请确认业务是否应新建任务。

参数说明

string
required
API Key 鉴权信息,格式为 Bearer YOUR_API_KEY
string
required
固定为 application/json
string
可选。客户端幂等键;亦可用 X-Idempotency-Key。同用户同键约 24 小时内重放原 task_id,不重复扣费。详见上文「幂等提交」。
string
default:"doubao-seedance-2-0-fast"
required
视频模型 ID。Token 计费:doubao-seedance-2-5doubao-seedance-2-0doubao-seedance-2-0-fastdoubao-seedance-2-0-mini(fast/mini 不支持 1080p;2.5 支持到 1080p、不支持 4k)。
string
default:"一款智能手表在白色展示台上缓慢旋转,柔和棚拍光线,镜头平稳推进"
required
视频描述文本。
string
default:"5"
视频时长(秒),传字符串如 "5"。优先于顶层 duration。也可传 "-1" 智能时长。2.54–30-1
number
时长整数,兼容 OpenAI Video 客户端。若同时传 seconds,以 seconds 为准;支持 -1
string
default:"720p"
官方分辨率枚举。doubao-seedance-2-0 支持到 4kdoubao-seedance-2-5 支持 480p / 720p / 1080p;fast / mini 仅 480p/720p。与 metadata.resolution 等价;不支持像素串。
string[]
公网图片 URL 列表,用于简单图生视频。多模态或需指定首帧/参考角色时,请使用 metadata.content
string
回调通知地址。传入后任务状态变化时上游主动向该地址 POST 推送结果,免轮询;详见上文「回调通知」。
object
扩展参数,字段名与上游 ARK 一致:contentresolutionratiooutput_format(2.5)、generate_audioreturn_last_frameseed 等。
string
输出分辨率,优先级高于 size。2.5 支持 480p / 720p / 1080p(不含 4k)。
string
宽高比,如 16:99:16adaptive。首尾帧 / 编辑 / 延长任务建议 adaptive
string
仅 Seedance 2.5:输出封装 mp4(默认)或 mov
string
仅 Seedance 2.5:全模态参考任务的子类型引导,可选 auto(默认,按素材+提示词自动判定)、reference(参考生视频,ratio/duration 无特殊限制)、edit(视频编辑,要求 contentreference_video(或裸 video_url)、ratio=adaptiveduration=-1)、extend(视频延长,要求 contentreference_video(或裸 video_url)、ratio=adaptive)。显式指定可在提交时前置校验参数,减少任务创建后的异步报错(InvalidParameter.TaskTypeConstraint)。
object[]
多模态输入数组。每项含 typeimage_url / video_url / audio_url)、对应 URL 对象,以及可选 role(见上文 role 表)。2.5 素材上限约图 ≤30 / 视频 ≤10 / 音频 ≤10(合计 ≤50)。

响应体

string
视频生成任务 ID。
string
视频生成任务 ID。部分响应会同时返回 idtask_id
string
任务状态,例如 queued
string
本次任务使用的模型 ID。