国内 Seedance 视频生成接口文档

更新日期：2026-09-02

1. 本次更新与兼容说明

主要更新如下：

新增 doubao-seedance-2-5-260628。
分辨率 480P、720P、1080P 大小写均可，平台会归一化。
平台创建接口以 task_id 为稳定任务标识；id 和其他任务对象字段为可选兼容字段。
平台接口与火山方舟兼容接口使用不同的错误对象格式，详见对应章节。

2. 通用约定

BASE_URL：平台服务地址，本文示例使用 https://api.openfde.work。
API_KEY：在平台“令牌”页面创建的 sk- 开头密钥。
认证请求头：Authorization: Bearer $API_KEY。
JSON 请求头：Content-Type: application/json。
任务为异步执行，建议每 5 至 10 秒查询一次，直到成功或失败。
生成结果 URL 应视为临时地址，通常约 24 小时有效，成功后请立即下载保存。
提交时根据模型、分辨率和请求时长预扣，完成后按实际用量结算，多退少补；任务失败自动退款。

export BASE_URL="https://api.openfde.work"
export API_KEY="sk-xxxxxxxx"

2.1 支持模型

模型名称	文生视频	图生视频	多模态参考
`doubao-seedance-2-5-260628`	支持	支持	支持图片、视频和音频参考

调用方只需要使用参考环境模型名称，无需关心任务的具体执行方式。同名模型的执行过程对调用方透明。

2.2 接口总览

接口格式	创建任务	查询任务
平台接口	`POST /v1/video/generations`	`GET /v1/video/generations/{id}`
火山方舟兼容接口	`POST /api/v3/contents/generations/tasks`	`GET /api/v3/contents/generations/tasks/{id}`

每次创建请求都会产生一个独立计费任务。不要为同一次生成同时请求两套创建接口。

3. 平台接口

3.1 创建任务

POST $BASE_URL/v1/video/generations

Seedance 2.5 多模态生成

Seedance 2.5 使用结构化 media 指定每个媒体的用途：

curl --location "$BASE_URL/v1/video/generations" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "参考角色形象和音频节奏生成舞台表演，镜头保持稳定",
    "size": "720P",
    "duration": 8,
    "media": [
      {"type": "reference_image", "url": "https://example.com/character.jpg"},
      {"type": "reference_audio", "url": "https://example.com/music.mp3"}
    ],
    "metadata": {
      "aspect_ratio": "16:9",
      "generate_audio": true,
      "watermark": false,
      "return_last_frame": true,
      "seed": 123456
    }
  }'

media[].type 支持：

类型	用途
`reference_image`	参考图
`first_image`	首帧图
`last_image`	尾帧图
`reference_video`	参考视频
`reference_audio`	参考音频

Seedance 2.5 输入限制：

图片类媒体总数最多 30 个。
参考视频最多 10 个。
参考音频最多 10 个。
media 不能与 image、images 或 videos 同时使用。
使用 first_image 或 last_image 时，画面比例必须为 adaptive；未传比例时平台自动使用 adaptive。
视频编辑请求应使用 ratio=adaptive 和 duration=-1；输入视频时长应为 4 至 30 秒。

Seedance 2.5 视频编辑示例

视频编辑没有单独的动作字段。模型根据提示词和 reference_video 判断编辑意图，因此提示词应明确说明需要保留和修改的内容。

curl --location "$BASE_URL/v1/video/generations" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "在保留原主体、动作和时长的前提下，将参考视频调整为电影质感",
    "size": "480P",
    "duration": -1,
    "media": [
      {
        "type": "reference_video",
        "url": "https://example.com/input.mp4"
      }
    ],
    "metadata": {
      "aspect_ratio": "adaptive",
      "generate_audio": false,
      "watermark": false
    }
  }'

media[].url 可以使用可公开访问的 HTTP(S) 视频 URL，也可以使用状态为 active 的平台视频素材引用，例如 asset://va-example-video。

视频编辑必须满足以下条件：

使用 duration=-1 和 metadata.aspect_ratio="adaptive"。
输入视频时长必须为 4 至 30 秒。
输出视频的时长和画面比例跟随输入视频。
创建接口返回任务 ID 只表示请求已受理；媒体校验或上游处理失败时，任务可能随后进入失败状态，客户端必须继续轮询到终态。

平台请求参数

字段	必填	说明
`model`	是	使用参考环境模型名称
`prompt`	是	非空提示词
`image`	否	单张图片，兼容字段，平台归一为 `images`
`images`	否	图片 URL、Base64/data URI 或平台图片素材引用
`videos`	否	参考视频 URL 或平台视频素材引用；仅在目标模型明确支持时使用
`media`	否	Seedance 2.5的结构化媒体，可指定 `first_image`、`last_image`、`reference_image`、`reference_video`、`reference_audio`；不能与旧媒体字段混用
`size`	否	`480P`、`720P`、`1080P`，大小写不敏感
`duration`	否	4 至 30 秒，视频编辑可使用 `-1`
`seconds`	否	`duration` 的历史兼容字段；同时存在时优先使用 `duration`
`metadata.aspect_ratio`	否	画面比例；兼容别名 `metadata.ratio`
`metadata.generate_audio`	否	是否生成输出音轨，布尔值；Seedance 2.5支持，使用参考音频时应设置为 `true`
`metadata.audio_generation`	否	`metadata.generate_audio` 的存量别名，兼容 `Enabled` 或 `Disabled`
`metadata.watermark`	否	是否添加水印，布尔值；是否生效取决于模型能力
`metadata.negative_prompt`	否	存量反向提示词字段；是否生效取决于模型能力
`metadata.seed`	否	Seedance 2.5 随机种子，64 位整数
`metadata.return_last_frame`	否	Seedance 2.5 是否返回尾帧 URL

3.2 创建响应

创建成功返回 HTTP 200。task_id 是平台接口稳定的任务标识，必须保存并用于查询。

完整异步视频对象示例：

{
  "id": "06a8596c-811f-7bb4-8000-29e0b48cc671",
  "task_id": "06a8596c-811f-7bb4-8000-29e0b48cc671",
  "object": "video",
  "model": "doubao-seedance-2-5-260628",
  "status": "queued",
  "progress": 0,
  "created_at": 1784800000
}

3.3 查询任务

GET $BASE_URL/v1/video/generations/{task_id}

curl --location "$BASE_URL/v1/video/generations/06a8596c-811f-7bb4-8000-29e0b48cc671" \
  --header "Authorization: Bearer $API_KEY"

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "06a8596c-811f-7bb4-8000-29e0b48cc671",
    "action": "generate",
    "status": "SUCCESS",
    "fail_reason": "https://example.com/video.mp4",
    "submit_time": 1784800000,
    "start_time": 1784800005,
    "finish_time": 1784800060,
    "progress": "100%",
    "data": {}
  }
}

字段	说明
`data.status`	`NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`、`SUCCESS` 或 `FAILURE`
`data.progress`	字符串百分比，例如 `50%`、`100%`
`data.fail_reason`	`SUCCESS` 时为视频 URL，`FAILURE` 时为失败原因，必须结合状态判断
`data.data`	历史兼容的不透明扩展对象，结构可能变化，客户端不得依赖其内部字段

3.4 平台错误格式

平台接口沿用存量的扁平错误对象：

{
  "code": "invalid_request",
  "message": "duration must be between 4 and 15 seconds",
  "data": null
}

客户端应依据 HTTP 状态码和顶层 code 处理失败。message 用于辅助排查，文案可能调整；data 可能为 null 或扩展数据，不得依赖固定结构。

4. 火山方舟兼容接口

4.1 创建任务

POST $BASE_URL/api/v3/contents/generations/tasks

Seedance 2.5 多模态示例

curl --location "$BASE_URL/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {"type": "text", "text": "参考角色形象和音频节奏生成舞台表演"},
      {
        "type": "image_url",
        "image_url": {"url": "https://example.com/character.jpg"},
        "role": "reference_image"
      },
      {
        "type": "audio_url",
        "audio_url": {"url": "https://example.com/music.mp3"},
        "role": "reference_audio"
      }
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 8,
    "generate_audio": true,
    "watermark": false,
    "seed": 123456,
    "return_last_frame": true,
    "output_format": "mp4"
  }'

Seedance 2.5 视频编辑示例

curl --location "$BASE_URL/api/v3/contents/generations/tasks" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "doubao-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "在保留原主体、动作和时长的前提下，将参考视频调整为电影质感"
      },
      {
        "type": "video_url",
        "video_url": {
          "url": "https://example.com/input.mp4"
        },
        "role": "reference_video"
      }
    ],
    "resolution": "480p",
    "ratio": "adaptive",
    "duration": -1,
    "generate_audio": false
  }'

video_url.url 可以使用可公开访问的 HTTP(S) 视频 URL，也可以使用状态为 active 的平台视频素材引用，例如 asset://va-example-video。视频编辑意图由提示词和参考视频共同确定；输入视频必须为 4 至 30 秒，输出时长和画面比例跟随输入视频。创建成功后仍须轮询到 succeeded、failed 或 cancelled，不能把取得任务 ID 视为编辑成功。

火山方舟兼容接口当前仅支持 output_format="mp4"。camera_fixed=true、draft、draft_task、frames、callback_url、safety_identifier、execution_expires_after、priority、omni_reference_task_type 和 tools 等未支持参数传入非空值时会返回 HTTP 400。

创建成功：

{
  "id": "06a8596c-811f-7bb4-8000-29e0b48cc671"
}

该响应仅表示任务已创建，后续必须使用查询接口轮询到终态。

4.2 查询任务

GET $BASE_URL/api/v3/contents/generations/tasks/{id}

{
  "id": "06a8596c-811f-7bb4-8000-29e0b48cc671",
  "model": "doubao-seedance-2-5-260628",
  "status": "succeeded",
  "content": {
    "video_url": "https://example.com/video.mp4",
    "last_frame_url": "https://example.com/last-frame.jpg"
  },
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 8,
  "generate_audio": true,
  "created_at": 1784800000,
  "updated_at": 1784800060
}

状态	说明
`queued`	已提交或排队中
`running`	正在生成
`succeeded`	成功，读取 `content.video_url`
`failed`	失败，读取 `error`
`cancelled`	已取消

4.3 火山方舟兼容错误格式

火山方舟兼容接口使用 error 包装的错误对象：

{
  "error": {
    "code": "InvalidParameter",
    "message": "duration must be -1 or between 4 and 30 seconds",
    "param": "duration",
    "type": "BadRequest"
  }
}

客户端应依据 HTTP 状态码和 error.code 处理失败，不应依赖 error.message 的固定文案。

5. 素材库

素材库用于保存审核通过的图片、视频和音频。上传后通过 asset://va-* 引用，无需在每次生成时重复上传。

5.1 上传素材

POST $BASE_URL/v1/video/assets

公网图片示例：

curl --location "$BASE_URL/v1/video/assets" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/character.jpg",
    "name": "角色参考图",
    "asset_type": "Image"
  }'

视频或音频素材使用同一接口，将 asset_type 设置为 Video 或 Audio。图片也可以通过 image 字段提交 Base64/data URI；url 和 image 二选一。视频和音频只支持公网 HTTP(S) URL。

创建成功：

{
  "id": "va-1784700000000-abc123",
  "name": "角色参考图",
  "status": "processing"
}

轮询以下接口，直到 status 为 active 或 failed：

GET $BASE_URL/v1/video/assets/{asset_id}

只有 active 素材可以用于生成。平台接口可以在 images、videos 或 media[].url 中引用；火山方舟兼容接口在对应的 image_url.url、video_url.url 或 audio_url.url 中引用。

5.2 管理素材

GET    $BASE_URL/v1/video/assets?limit=20&offset=0
DELETE $BASE_URL/v1/video/assets/{asset_id}

列表响应中的 limit_per_user 是当前账户素材上限。删除只能操作当前用户自己的素材。

5.3 素材限制

图片最大 20MB。
视频最大 100MB。
音频最大 15MB。
每用户配额统计 processing + active 素材，失败素材不占配额。
只能引用当前用户自己的 active 素材。
素材类型必须和引用字段匹配。
asset://va-* 是平台素材引用，不是永久公开下载 URL。

6. 常见 HTTP 状态码

HTTP 状态	说明
`400`	请求体或参数不合法
`401`	API Key 缺失、无效或已禁用
`403`	模型无权限或账户额度不足
`404`	任务或素材不存在，或者不属于当前用户
`409`	活动任务不能删除
`429`	请求过于频繁或服务繁忙
`502/503`	服务暂时不可用

收到 502/503 时，不要在未确认创建请求失败的情况下无限重复提交。查询请求超时不代表生成失败，应保留任务 ID 并稍后继续查询。

7. 推荐调用流程

选择一套创建接口提交任务并保存任务 ID。
每 5 至 10 秒查询一次状态。
成功后立即下载 video_url 或平台接口 fail_reason 中的视频。
失败后记录 HTTP 状态、错误码和请求 ID，再根据参数或服务状态决定是否重试。
客户端整体轮询超时建议设置为 10 至 20 分钟；超时不代表任务失败。
不要因单次查询超时重新创建同一个任务，避免产生重复计费任务。

8. 常见问题

401 或无权限：检查 Authorization: Bearer sk-xxx、令牌状态和令牌分组是否包含目标模型。
额度不足：创建时会预扣费用，请确认账户余额和令牌权限。
图片 URL 错误：公网 URL 必须能够直接访问；私有存储请使用有效的预签名 URL。
Base64 请求体过大：Base64 通常增加约三分之一体积，较大图片请先压缩或改用 URL/素材库。
多参考图效果不稳定：确认平台接口传了 metadata.usage="Reference"，或方舟兼容接口为每张图片设置了 role="reference_image"。
成功后没有下载视频：结果 URL 是临时地址，任务成功后应立即下载并自行持久化。

1. 本次更新与兼容说明​

2. 通用约定​

2.1 支持模型​

2.2 接口总览​

3. 平台接口​

3.1 创建任务​

Seedance 2.5 多模态生成​

Seedance 2.5 视频编辑示例​

平台请求参数​

3.2 创建响应​

3.3 查询任务​

3.4 平台错误格式​

4. 火山方舟兼容接口​

4.1 创建任务​

Seedance 2.5 多模态示例​

Seedance 2.5 视频编辑示例​

4.2 查询任务​

4.3 火山方舟兼容错误格式​

5. 素材库​

5.1 上传素材​

5.2 管理素材​

5.3 素材限制​

6. 常见 HTTP 状态码​

7. 推荐调用流程​

8. 常见问题​

1. 本次更新与兼容说明

2. 通用约定

2.1 支持模型

2.2 接口总览

3. 平台接口

3.1 创建任务

Seedance 2.5 多模态生成

Seedance 2.5 视频编辑示例

平台请求参数

3.2 创建响应

3.3 查询任务

3.4 平台错误格式

4. 火山方舟兼容接口

4.1 创建任务

Seedance 2.5 多模态示例

Seedance 2.5 视频编辑示例

4.2 查询任务

4.3 火山方舟兼容错误格式

5. 素材库

5.1 上传素材

5.2 管理素材

5.3 素材限制

6. 常见 HTTP 状态码

7. 推荐调用流程

8. 常见问题