Doubao Seedance 2.x 视频生成

功能概览

本页用于说明 Doubao Seedance 2.x 视频生成 的核心能力、调用入口和接入要点，帮助开发者快速判断适用场景并完成集成。

适用场景

• 产品原型验证：快速接入模型能力，验证内容生成、理解或编辑流程。
• 生产业务接入：用于批量任务、自动化工作流和多模型组合调用。
• 能力迁移适配：适合从原有模型或 SDK 平滑切换到爱虾AI统一接口。

接入建议

• 优先确认模型名称、请求路径和响应字段，再接入具体业务流程。
• 对异步任务、媒体生成和长耗时请求，建议在业务侧加入重试与状态轮询。
• 上线前建议准备日志追踪、错误处理和内容安全校验，便于稳定运行。

模型与网关限制

请求中推荐使用左列的平台模型名。网关会根据已配置的上游模型转发请求。fast 和 mini 传入 1080p 或 4k 会返回 400。

火山方舟官方可能提供更长时长或更多参数组合；以本接口的 4-15 秒限制为准。

鉴权与异步结算

所有请求均使用 Bearer 鉴权：

Authorization: Bearer <API_KEY>
Content-Type: application/json

官方兼容接口

官方兼容创建路径：

POST https://api.yisu-api.com/api/v3/contents/generations/tasks

查询、列表和取消路径：

GET    https://api.yisu-api.com/api/v3/contents/generations/tasks/{task_id}
GET    https://api.yisu-api.com/api/v3/contents/generations/tasks?page_num=1&page_size=20
DELETE https://api.yisu-api.com/api/v3/contents/generations/tasks/{task_id}

官方兼容接口透传火山方舟的任务结构。使用官方的 content 格式时，可使用文本、参考图片、参考视频、参考音频等输入。提交前请阅读下方参数说明，确认输入组合与模型限制。

文生视频

curl "https://api.yisu-api.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.5",
    "content": [
      {
        "type": "text",
        "text": "清晨的海岸公路，镜头缓慢向前推进，电影感自然光。"
      }
    ],
    "ratio": "16:9",
    "duration": 4,
    "resolution": "480p",
    "generate_audio": false,
    "watermark": false
  }'

图生视频

curl "https://api.yisu-api.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "让参考图中的产品缓慢旋转，背景光影轻微流动。"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/product.png"
        },
        "role": "reference_image"
      }
    ],
    "ratio": "1:1",
    "duration": 4,
    "resolution": "480p",
    "generate_audio": false
  }'

参考视频和音频分别使用 video_url、audio_url，并设置 role 为 reference_video、reference_audio。可用的数量与任务类型以火山方舟官方文档为准。

创建响应示例

{
  "id": "cgt-xxxxxxxxxxxxxxxx",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "created_at": 1780000000
}

任务状态通常为 queued、running、succeeded、failed、cancelled 或 expired。成功响应的 content.video_url 是视频地址。

查询任务

curl "https://api.yisu-api.com/api/v3/contents/generations/tasks/cgt-xxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer <API_KEY>"

任务未完成时继续轮询。建议每 5-10 秒查询一次，避免高频轮询。

OpenAI Videos API 兼容接口

OpenAI 兼容路径：

POST   https://api.yisu-api.com/v1/videos
GET    https://api.yisu-api.com/v1/videos/{video_id}
GET    https://api.yisu-api.com/v1/videos/{video_id}/content
GET    https://api.yisu-api.com/v1/videos
DELETE https://api.yisu-api.com/v1/videos/{video_id}

该接口兼容 OpenAI 的路径、任务对象与视频下载方式，但 Seedance 的核心生成参数仍使用 ratio、duration、resolution。不要用 seconds 代替 duration，也不要只传 size 期待其转换为上游分辨率。

文生视频

curl "https://api.yisu-api.com/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0-fast",
    "prompt": "雨后城市街道，霓虹灯在积水中倒映，镜头缓慢平移。",
    "ratio": "16:9",
    "duration": 4,
    "resolution": "480p",
    "generate_audio": false,
    "watermark": false
  }'

图生视频

OpenAI 兼容写法可用顶层 image 或 images。网关会转换为上游的 content.image_url 结构。

curl "https://api.yisu-api.com/v1/videos" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0-mini",
    "prompt": "让参考图中的人物回头看向镜头，保持人物外观一致。",
    "images": [
      "https://example.com/person.png"
    ],
    "ratio": "9:16",
    "duration": 4,
    "resolution": "480p",
    "generate_audio": false
  }'

也可传递 video / videos、audio / audios，分别转换为参考视频和参考音频。需要使用首尾帧或高级参数时，请在 /v1/videos 路径直接传递官方 content 数组；编辑、延长任务还需遵守下方参数说明中的模型与任务类型限制。

OpenAI 兼容响应

创建或查询时，网关将上游任务对象转换为以下格式，并在 upstream_response 中保留原始任务响应：

{
  "id": "cgt-xxxxxxxxxxxxxxxx",
  "object": "video",
  "created": 1780000000,
  "model": "doubao-seedance-2-0-fast-260128",
  "status": "queued",
  "content": null,
  "error": null,
  "upstream_response": {}
}

状态映射如下：

下载视频

任务状态为 completed 后，可由兼容下载接口直接获取 MP4：

curl "https://api.yisu-api.com/v1/videos/cgt-xxxxxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer <API_KEY>" \
  --output output.mp4

若任务尚未产生视频，接口返回 HTTP 409 及任务信息。

参数说明

以下说明依据火山方舟《创建视频生成任务》文档（官方页面更新于 2026-09-09），并结合当前网关的转发规则整理。两个创建路径使用相同的参数处理逻辑；输出时长按本页的 4-15 秒范围提交，不能直接照搬官方 Seedance 2.5 的 30 秒示例。

请求格式与参数优先级

请求体使用 JSON，Content-Type 为 application/json。整数直接传数字，布尔值传 true / false，不要传字符串 "false"。

• 完整写法： 传入 model 和非空的 content 数组，生成参数放在与 content 同级的请求体顶层。适合首尾帧、多模态参考、回调及其他官方参数。
• 简写方式： 不传 content，改用 prompt 和顶层 image / images、video / videos、audio / audios。网关将这些字段转换为官方 content 结构。
• 不要混用： 一旦传入数组形式的 content，网关不会再把顶层 prompt、images 等字段合并进去；提示词与素材应全部放入 content。不要传空数组并期待网关补入 prompt。
• 高级参数使用完整写法： 简写方式仅保留转换后的内容以及 ratio、duration、resolution、generate_audio、watermark、seed。callback_url、return_last_frame、output_format 等参数需要随 content 一起提交，否则不会转发。

基础生成参数

输出像素尺寸由 resolution 与 ratio 共同决定。参考图片比例与输出比例不一致时，上游可能居中裁剪；首尾帧比例不一致时以首帧为主，尾帧会裁剪适配。

Seedance 2.5 的 1080p、Seedance 2.0 的 4k 输出采用 10bit 位深及 H.265/HEVC 编码，播放端需要支持对应编码。

content 数组结构

每一项是独立对象。type、对应的素材对象或 text、以及 role 都放在该项内；role 不要写入 image_url / video_url / audio_url 对象中。

素材 URL 必须能被上游服务访问，不能使用本机路径、localhost 或内网地址。带有效期的签名 URL 应覆盖上游读取素材的时间。官方还定义了 asset://<ASSET_ID> 素材引用，但其可用性取决于上游账号的素材权限；通过本接口调用时优先使用公网 URL，不要默认自己的火山账号素材 ID 可以跨账号使用。

图片角色与任务组合

首帧、首尾帧、全模态参考是互斥场景。 不要在同一请求中同时传 first_frame / last_frame 和 reference_image / reference_video / reference_audio。若希望以参考图控制起止画面，可在全模态参考提示词中描述；需要严格指定首尾帧时，使用首尾帧角色。

参考素材数量与时长

以下为官方输入素材限制，和本接口 输出视频 4-15 秒 的范围分别计算。首帧 / 首尾帧任务仍分别只传 1 / 2 张图片。

含真人人脸的图片、视频等特殊素材还需符合官方素材使用规则；接口能够接收 URL 不代表上游一定接受该素材。

简写素材参数

这些参数仅在未传 content 数组时转换生效。完整写法与简写方式在两个创建路径上都可以使用。

同一类素材只选单数或复数形式；同时提供时，网关优先取单数字段，不会合并两个字段。推荐统一使用复数数组形式。

高级参数：随 content 一起提交

以下字段放在 JSON 顶层，不能放进 content 的文本项。网关透传这些字段，最终是否接受及如何执行由所选上游模型决定。

Seedance 2.5 任务类型约束

显式指定任务类型会让上游提前校验部分约束，但模型仍会结合提示词判断实际任务类型；两者不一致时，可能异步返回 InvalidParameter.TaskTypeMismatch。

回调处理

callback_url 可收到 queued、running、succeeded、failed、expired 状态。官方说明成功、失败通知在 5 秒内未收到成功响应时会重试，接收端应及时返回成功状态，并按任务 ID 与状态去重处理。回调地址不要填写本机或内网地址；仍建议保留轮询，避免漏收通知后无法取得结果。

不要直接套用的其他官方参数

官方参考页同时覆盖 Seedance 1.x。下列参数虽可能被网关透传，但官方当前未将其列为本文 2.5 / 2.0 系列的支持能力，不应作为本页模型的可用参数提交：

完整请求示例：首尾帧与尾帧返回

以下请求使用 2.0 模型。改为 2.5 时，首帧 / 首尾帧场景必须保持 ratio=adaptive。在 /v1/videos 路径也可提交相同请求体。

{
  "model": "doubao-seedance-2.0",
  "content": [
    {"type": "text", "text": "镜头缓慢推进，让首帧场景自然过渡到尾帧场景。"},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/start.png"},
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/end.png"},
      "role": "last_frame"
    }
  ],
  "duration": 6,
  "resolution": "720p",
  "ratio": "adaptive",
  "generate_audio": false,
  "watermark": false,
  "return_last_frame": true
}

完整请求示例：多模态参考与回调

提交前替换素材 URL 和回调地址，并确认素材满足数量、时长及文件大小限制。

{
  "model": "doubao-seedance-2.5",
  "content": [
    {"type": "text", "text": "保持参考图中的产品外观，参考视频的运镜，按参考音频的节奏展示产品。"},
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/product.png"},
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {"url": "https://example.com/motion.mp4"},
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://example.com/music.mp3"},
      "role": "reference_audio"
    }
  ],
  "duration": 8,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": true,
  "watermark": false,
  "omni_reference_task_type": "reference",
  "output_format": "mp4",
  "callback_url": "https://example.com/callbacks/seedance",
  "execution_expires_after": 86400
}

常见错误