Seedance 系列

使用异步视频接口。本章覆盖 EP 系列与对应 Doubao 模型，客户端不需要填写内部线路名。

模型与输出规格

模型 ID	建议生成时长	分辨率
`dreamina-seedance-2-0-ep`	4–15 秒	`480p` / `720p` / `1080p` / `4k`
`dreamina-seedance-2-0-fast-ep`	4–15 秒	`480p` / `720p`
`dreamina-seedance-2-0-mini-ep`	4–15 秒	`480p` / `720p`
`dreamina-seedance-2-5-ep`	4–30 秒	`480p` / `720p` / `1080p`
`doubao-seedance-2-0-260128`	4–15 秒	`480p` / `720p` / `1080p` / `4k`
`doubao-seedance-2-0-fast-260128`	4–15 秒	`480p` / `720p`
`doubao-seedance-2-0-mini-260615`	4–15 秒	`480p` / `720p`
`doubao-seedance-2-5-260628`	4–30 秒	`480p` / `720p` / `1080p`

按范围内的整数传 duration，不局限于 5 / 10 / 15 秒。官转 2.5 还支持 duration: -1，表示由模型决定输出时长；此值不是单独的编辑模式。不同分组可用模型以 /v1/models 为准。

支持的比例：16:9、9:16、1:1、4:3、3:4、21:9、adaptive。建议总是明确填写 resolution 和 duration，不要依赖不同线路的默认分辨率。

文生视频

省略 mode 和参考素材。

{
  "model": "dreamina-seedance-2-0-ep",
  "prompt": "A slow aerial shot over a green valley at sunrise, natural light, steady camera.",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": true,
  "watermark": false
}

audio 控制是否生成音轨；watermark 控制水印。本章 EP 系列不承诺 seed 可复现结果，请勿依赖种子固定。

首帧、尾帧、首尾帧

使用 mode: "first_last_frame"，至少提供一个显式帧字段：

只有 first_frame_url：首帧生成。
只有 last_frame_url：尾帧生成，不要把尾帧放进 image_urls[0]。
两者都有：首尾帧生成。

{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "The character turns slowly toward the camera. Keep the face and outfit consistent.",
  "mode": "first_last_frame",
  "first_frame_url": "https://example.com/first.png",
  "last_frame_url": "https://example.com/last.png",
  "duration": 8,
  "resolution": "1080p",
  "aspect_ratio": "adaptive",
  "audio": true
}

输出比例跟随输入帧。建议 aspect_ratio: "adaptive"；不要期待通过固定比例把输入帧变成另一个比例。需要特定比例时先裁剪素材。

只传尾帧：

{
  "model": "dreamina-seedance-2-0-fast-ep",
  "prompt": "The camera slowly approaches the final composition.",
  "mode": "first_last_frame",
  "last_frame_url": "https://example.com/last.png",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}

首尾帧模式不要混入 reference_video_urls、reference_audio_urls。旧的位置数组写法仍可兼容首帧 / 首尾帧，但新接入使用显式帧字段，避免用途混淆。

全能参考

使用 mode: "multi_ref"。图片是形象 / 风格参考，视频可提供动作与镜头，音频提供声音参考。至少提供一张图片或一段视频，再按需附加音频，避免仅音频请求。

{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Keep the character from image 1, follow the movement in video 1 and the mood of audio 1.",
  "mode": "multi_ref",
  "image_urls": [
    "https://example.com/character.png"
  ],
  "reference_video_urls": [
    "https://example.com/motion.mp4"
  ],
  "reference_audio_urls": [
    "https://example.com/music.mp3"
  ],
  "metadata": {
    "reference_video_seconds": 8.4,
    "reference_audio_seconds": 6
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "9:16",
  "audio": true
}

参考视频和音频的实际时长由服务端检测，调用方不必填写。metadata.reference_video_seconds 和 metadata.reference_audio_seconds 保留兼容，校验和费用预估以服务端检测值为准。

参考限制

系列	图片	视频	音频	时间边界
2.0 / Fast / Mini	最多 9 张	最多 3 段	最多 3 段	标称单段 2–15 秒，视频与音频分别累计不超过 15 秒
2.5	最多 30 张	最多 10 段	最多 10 段	标称单段 2–30 秒，视频与音频分别累计不超过 30 秒

本站为编码时间误差保留边界余量：最小 1.8 秒，2.0 的最大 / 累计校验边界 15.2 秒，2.5 为 30.2 秒。余量不是建议的目标长度，也不改变生成时长上限；尽量按标称范围准备素材。

图片建议采用 JPEG / PNG 等常用格式。官转 Seedance 2.5（包括对应 EP、经济版和 face-library 线路）的参考图、首帧、尾帧均要求：宽和高各为 300–6000px，宽高比在 0.4–2.5 之间，单文件不超过 30MB。

游乐场上传时提前检查，服务端也会在预扣费和提交上游前读取实际图片进行校验；外链、Base64 和历史参数复用同样适用，客户端填写宽高不能绕过检查。不符合要求返回 HTTP 400、invalid_reference_media，说明图片序号、实际尺寸和限制，不会自动缩放。例如 reference_images[2] has dimensions 290x382: shortest side must be at least 300px 表示第三张图片过小。无法下载或识别图片时也会明确拒绝，请更换素材后重新提交。

asset:// 是上游登记素材的标识，不作为图片网址下载；仍沿用素材登记与状态检查。其他渠道以模型能力接口公布的限制为准，不将某个模型或登记流程的边界套用到全部线路。

Seedance 2.5 参考、编辑与延长

这三种意图都使用 mode: "multi_ref"。可选的顶层字段 omni_reference_task_type 用于提前校验参数；省略时为 auto。它不会强制改变模型对提示词的理解，请让提示词与指定意图一致。

`omni_reference_task_type`	含义	参考视频	`aspect_ratio`	`duration`
`auto`（默认）	根据提示词和素材识别意图	按实际需求	推荐 `adaptive`	推荐 `-1`，也可填 4–30 的整数，但须符合实际意图
`reference`	参考素材生成新视频	可选	支持固定比例或 `adaptive`	4–30 的整数或 `-1`
`edit`	修改已有视频	至少一段，每段 4–30 秒	必须 `adaptive`	必须 `-1`，跟随被编辑的视频
`extend`	延长已有视频	至少一段，每段 2–30 秒	必须 `adaptive`	4–30 的整数或 `-1`

编辑和延长也可同时提供图片、其他参考视频和音频，仍受上表的数量和累计时长限制。多段视频时，模型根据提示词选择编辑或延长的对象。音频不能作为唯一参考素材。

不打算区分子任务时，建议 auto + adaptive + -1，并将参考视频准备为 4–30 秒，以同时满足编辑意图的下限。-1 不保证某个固定秒数，也不要把它套用到 2.0、Venice 或其他未声明支持的线路。

编辑已有视频

明确描述保留什么、修改什么。输出宽高比和时长跟随模型选中的原视频：

{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Edit the video: replace the background with a snowy city, preserve the camera movement.",
  "mode": "multi_ref",
  "omni_reference_task_type": "edit",
  "image_urls": [
    "https://example.com/background.png"
  ],
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": -1,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}

延长已有视频

明确描述在原视频后继续发生的动作。输出比例跟随输入视频，duration 是请求的输出视频时长，不是自行假定的拼接后总长度：

{
  "model": "dreamina-seedance-2-5-ep",
  "prompt": "Extend the video: continue the camera movement as the character walks toward the snowy city.",
  "mode": "multi_ref",
  "omni_reference_task_type": "extend",
  "reference_video_urls": [
    "https://example.com/input.mp4"
  ],
  "metadata": {
    "reference_video_seconds": 8.4
  },
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "adaptive"
}

参数检查与错误处理

显式指定 edit / extend 时，本站先检查是否有视频、是否使用 adaptive，以及编辑时是否传入 -1。
服务端检测每个音视频文件的时长，分别累计后检查上限；填写 metadata 不能替代文件检查。每个文件的尺寸、格式仍须满足供应商要求。
省略子任务类型或使用 auto 时，模型识别的实际意图与固定比例/时长不兼容，可返回 InvalidParameter.TaskTypeConstraint。
指定的子任务类型与提示词表达的意图冲突，可返回 InvalidParameter.TaskTypeMismatch。请修改提示词或类型后由调用方决定是否重新提交。

字段定义和任务类型边界依据官方创建视频任务文档及Seedance 2.5 参数约束。本站统一接口使用 aspect_ratio，会转为上游的 ratio。

Seedance 2.5 草稿与高清生成

已验证的 Doubao 2.5 和标准 EP 2.5 线路可先生成 480p 草稿，再用同一草稿生成 1080p 正式视频。是否开放以模型能力中的 contract.draft 为准；不要将此能力套用到经济版、特价版或其他未声明支持的线路。

第一步：生成草稿

通过 POST /v1/video/generations 提交 JSON，在正常生成参数上增加顶层 draft: true，且 resolution 必须为 480p。仍支持该模型允许的首尾帧和全能参考参数。

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "A red cube slowly rotates on a table, fixed camera.",
  "duration": 4,
  "aspect_ratio": "16:9",
  "resolution": "480p",
  "draft": true,
  "audio": false,
  "watermark": false
}

用返回的本站 task_... ID 查询 GET /v1/video/generations/{task_id}。成功后，响应 metadata 提供 draft、draft_can_finalize、draft_expires_at（Unix 秒）。只有 draft_can_finalize: true 且未过期的草稿才可继续生成；不要使用上游任务 ID 或视频 URL 替代。

第二步：估价并确认生成 1080p

向 POST /v1/video/generations/estimate 提交以下参数，读取 estimated_cost_usd。估价不发起生成、不扣费；随后向 POST /v1/video/generations 提交同一份参数，并可将报价放入 max_cost_usd。

{
  "model": "doubao-seedance-2-5-260628",
  "draft_task_id": "task_replace_with_your_completed_draft_id",
  "resolution": "1080p",
  "watermark": false
}

必须是本人已成功的草稿，model 与草稿一致，resolution 必须为 1080p。
正式生成继承草稿设置。不要再次传提示词、模式、时长、比例、种子、声音、参考素材或 metadata，即使取值未变也应省略；draft 省略或为 false。
服务端锁定草稿原线路和原账号，不切换至普通高清备用线路。原账号被停用、权限变化或草稿过期会明确报错，不自动重新生成草稿。
max_cost_usd 限制本次预扣报价。价格上涨时返回 HTTP 409、approval_price_changed，请重新估价并确认。它不是最终实际用量的硬性封顶。
草稿和正式视频是两个任务，分别预扣、分别结算，不是补差价。原草稿不再计作额外参考视频；原请求已有的参考视频费用仍按对应规则计算。
可用期以返回的 draft_expires_at 为准。草稿过期不删除已生成的视频，只是不再允许继续生成高清版本。部分正式视频采用 HEVC 编码，播放器需支持对应格式。

草稿及升级请求仅接受 JSON，不接受 multipart。视频游乐场和无限画布均提供草稿开关：游乐场在结果区操作；画布选中已完成的草稿视频后，可重新估价并确认高清生成。高清结果在画布中新增独立节点，保留原草稿。

计费

按视频 token 计费。不同分辨率、是否有参考视频，对应不同的每百万 token 单价。图片 / 音频参考不应被当作视频输入时长。

提交时按估算预扣，任务完成后按实际用量结算。实际输出尺寸、时长和参考视频都会影响费用；不能用文字 token 估算器计算视频 token。详细单价与当前 Key 的适用价格见模型广场，响应字段见计费与结算。

官转 2.5 使用自动时长时，按 30 秒输出估算预扣；显式编辑且已知参考视频总时长时，按该时长保守估算。最终仍以实际用量结算，多余预扣退回。