Seedance 国内线路

本文面向通过 AnyRoute 调用 doubao-seedance-2.0 模型的开发者，介绍视频生成、私有素材、真人认证和公域人物接口。

视频生成采用异步任务模式：提交任务后保存任务 ID，再查询任务状态并通过平台结果接口读取视频。

1. 基础信息

1.1 Base URL

https://biz.anyroute.io

也可以使用管理员提供的其他 AnyRoute 接入域名。本文示例统一使用：

1.2 鉴权

所有客户接口均使用 AnyRoute Bearer Token：

发送 JSON 时还需要：

1.3 资源 ID

平台返回以下资源 ID：

task_xxx      视频任务
asset_xxx     私有素材
assetgrp_xxx  素材组
authsess_xxx  真人认证会话
char_xxx      公域人物

只能使用平台返回的完整 ID，不要自行构造或修改资源 ID。

私有任务、素材、素材组和真人认证会话按用户隔离。同一用户创建的多个 API Token 可以读取该用户自己的资源，但不能读取其他用户的私有资源。

2. 模型和能力

本文模型名：

doubao-seedance-2.0

实际可用性和价格以 AnyRoute 价格页面及当前 API Token 权限为准。

2.1 已支持的视频输入

`type`	载荷字段	支持的 `role`
`text`	`text`	不传 `role`
`image_url`	`image_url.url`	`reference_image`、`first_frame`、`last_frame`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`

媒体地址支持：

图片：公网 HTTPS URL、asset://asset_xxx、asset://char_xxx、受限 Base64 Data URL。

视频：公网 HTTPS URL或 asset://asset_xxx。

音频：公网 HTTPS URL、asset://asset_xxx、受限 Base64 Data URL。

不支持裸 Base64、Base64 视频或 multipart/form-data。

2.2 Base64 图片

格式：

data:image/jpeg;base64,<BASE64_DATA>

允许 jpeg、png、webp、bmp、tiff、gif，格式名必须小写。单张图片解码后必须小于 30 MB，声明格式必须与文件内容一致。

2.3 Base64 音频

格式：

data:audio/mp3;base64,<BASE64_DATA>

当前模型允许 wav、mp3。单段音频要求 2-15 秒且不超过 15 MB，最多 3 段，所有参考音频总时长不超过 15 秒。

参考音频不能作为唯一参考输入，必须同时提供至少一张参考图片或一个参考视频。

单次请求体和内联媒体总量不得超过 64 MB。

2.4 视频参数

字段	类型	说明
`model`	string	必填，固定使用公开模型名
`content`	array	必填，1-64 项
`duration`	integer	可选，`-1`（模型自动选择）或 4-15 秒；与 `frames` 互斥
`frames`	integer	可选，1-360；与 `duration` 互斥
`resolution`	string	可选，支持 `480p`、`720p`、`1080p`
`ratio`	string	可选，支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`
`seed`	integer	可选，范围 `-1` 到 `4294967295`
`generate_audio`	boolean	可选，是否生成音频
`watermark`	boolean	可选，是否添加水印
`return_last_frame`	boolean	可选，是否返回尾帧
`service_tier`	string	可选，当前仅支持 `default`
`execution_expires_after`	integer	可选，3600-259200 秒
`callback_url`	string	可选，接收任务回调的公网 HTTPS URL
`tools`	array	可选，当前每项仅支持 `{"type":"web_search"}`；平台安全上限为 16 项

当前模型不支持 camera_fixed、draft 和 priority；即使传 false 或 0 也属于显式提供参数并会被拒绝。4k 不受支持，提交时返回 unsupported_video_parameter。

图片素材有三种互斥场景：单首帧、首尾帧、多模态参考。首帧/首尾帧不能与 reference_image、reference_video、reference_audio 混用；尾帧不能单独提供。多模态参考最多 9 张参考图片、3 个参考视频和 3 段参考音频。图片或视频的尺寸、时长、帧率以及所有媒体总时长由平台和当前模型最终校验。

duration: -1 表示由当前模型自动选择时长。平台在任务提交阶段按 15 秒上限预扣，任务完成后再按可信 usage 结算，不会把 -1 当作负数计费。

请求使用严格 JSON 校验。未知字段会返回 400 invalid_request，不会被静默忽略。

3. 创建视频任务

支持 Idempotency-Key。建议每个业务订单使用一个稳定且唯一的 Key。

3.1 文生视频

3.2 公网图片生成视频

3.3 私有素材生成视频

私有素材必须处于 active 状态：

3.4 首尾帧

{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "从第一帧平滑过渡到最后一帧"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/first.jpg"},
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://media.example.com/last.jpg"},
      "role": "last_frame"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "return_last_frame": true
}

3.5 参考视频

{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "参考视频中的动作节奏，保持主体外观一致"
    },
    {
      "type": "video_url",
      "video_url": {"url": "asset://asset_xxx"},
      "role": "reference_video"
    }
  ],
  "duration": 4,
  "resolution": "720p",
  "ratio": "16:9"
}

3.6 图片加参考音频

{
  "model": "doubao-seedance-2.0",
  "content": [
    {
      "type": "text",
      "text": "参考人物和音频生成自然讲述视频"
    },
    {
      "type": "image_url",
      "image_url": {"url": "asset://asset_xxx"},
      "role": "reference_image"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "asset://asset_xxx"},
      "role": "reference_audio"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": true
}

3.7 创建响应

提交结果确定时返回 200：

{
  "id": "task_xxx"
}

如果平台已建立任务，但暂时无法确认提交结果，可能返回 202，响应中仍包含同一个任务 ID。此时不要重新提交，应查询该任务。

平台不会因超时、断连、429 或 5xx 自动重新发送同一个创建请求。

4. 查询视频任务

成功响应：

{
  "id": "task_xxx",
  "model": "doubao-seedance-2.0",
  "status": "succeeded",
  "progress": 100,
  "error": null,
  "created_at": 1783670400,
  "updated_at": 1783670580,
  "content": {
    "video_url": "https://biz.anyroute.io/v1/videos/task_xxx/content",
    "last_frame_url": "https://biz.anyroute.io/v1/videos/task_xxx/last-frame"
  },
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  },
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "seed": 123456,
  "framespersecond": 24,
  "generate_audio": false,
  "watermark": false,
  "return_last_frame": true
}

任务状态：

queued | running | cancelled | succeeded | failed | expired

progress 为 0-100 的归一化整数。只有成功任务才会返回结果地址。没有可信 usage 时，平台不会生成该字段。

任务详情不会返回 Prompt、输入媒体 URL、Base64 内容、平台处理信息或原始结果地址。

5. 查询任务列表

参数	说明
`page_num`	默认 1，范围 1-500
`page_size`	默认 20，范围 1-500
`filter.status`	可重复，筛选任务状态
`filter.task_ids`	可重复，最多 100 个任务 ID
`filter.model`	按模型筛选
`filter.service_tier`	按 service tier 筛选

{
  "items": [],
  "total": 0
}

列表只返回当前用户最近 7 天的任务。更早的任务仍可通过任务详情接口查询。

6. 获取视频和尾帧

6.1 获取视频

6.2 获取尾帧

结果接口必须携带属于任务 owner 的 Bearer Token，支持标准 HTTP Range 请求，并使用 private, no-store。结果已过期且无法安全刷新时返回 410 video_result_expired。

7. 删除视频任务

成功删除已经结束的任务时返回 204，无响应体。

平台使用同一个 DELETE 接口处理取消或删除：

queued：请求取消任务。

running：返回 task_not_cancellable。

succeeded、failed、expired、cancelled：删除终态任务记录。

删除任务不会删除计费和审计记录。

8. 视频任务回调

创建任务时可以提供公网 HTTPS callback_url。平台在任务状态变化时向该地址发送 POST 回调。

回调是至少一次投递，接收方必须按 event_id 去重。回调失败不会改变任务状态、结果或计费。

{
  "event_id": "evt_xxx",
  "type": "succeeded",
  "created_at": 1783670580,
  "data": {
    "id": "task_xxx",
    "model": "doubao-seedance-2.0",
    "status": "succeeded",
    "error": null,
    "created_at": 1783670400,
    "updated_at": 1783670580,
    "version": 4,
    "content": {
      "video_url": "https://biz.anyroute.io/v1/videos/task_xxx/content"
    }
  }
}

回调头：

X-New-Api-Event-Id
X-New-Api-Task-Id
X-New-Api-Timestamp
X-New-Api-Signature: v1=<hex hmac-sha256>

9. `/v1/videos` 兼容接口

V3 是推荐入口。需要 OpenAI 风格视频对象时，可以使用：

V1 和 V3 共用同一个任务系统，可以交叉查询同一个任务。V1 同样只接受 JSON，不支持 Multipart。

10. 创建普通素材组

支持 Idempotency-Key。

成功返回 201：

{
  "id": "assetgrp_xxx",
  "object": "asset_group",
  "name": "presenter-assets",
  "description": "Presenter private assets",
  "group_type": "AIGC",
  "status": "active",
  "route_group_id": "g000xx",
  "route_group_name": "Seedance 服务分组展示名称",
  "created_at": 1783670400,
  "updated_at": 1783670400
}

route_group_name 是当前服务分组的对外展示名称。后续创建普通素材时应使用响应中的 assetgrp_xxx 作为 group_id。

客户只能直接创建 group_type: "AIGC"。真人素材组必须通过真人认证流程生成，不能直接创建 LivenessFace 素材组。

11. 查询素材组

11.1 素材组列表

支持 limit、after、status 和 route_group_id。limit 默认 20，范围 1-100。

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

11.2 素材组详情

素材组状态：

creating | active | failed | create_unknown | invalid |
deleting | deleted | delete_failed

12. 创建私有素材

支持 Idempotency-Key。素材创建只接受 JSON，url 必须是可公开访问的 HTTPS URL。

素材库不接受 Base64、asset:// 或 Multipart 上传。平台不保存素材文件二进制。

asset_type 支持：

Image | Video | Audio

普通素材必须传 group_id。真人素材应传真人认证会话返回的 asset_group_id。

创建返回 202：

{
  "id": "asset_xxx",
  "object": "asset",
  "name": "presenter-front",
  "asset_type": "Image",
  "status": "processing",
  "group_id": "assetgrp_xxx",
  "route_group_id": "g000xx",
  "route_group_name": "Seedance 服务分组展示名称",
  "created_at": 1783670400,
  "updated_at": 1783670400
}

素材状态：

creating | processing | active | failed | create_unknown |
invalid | deleting | deleted | delete_failed

只有 active 素材可以用于视频。

13. 查询和刷新素材

13.1 素材列表

支持 limit、after、status、asset_type、group_id 和 route_group_id。

{
  "object": "list",
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

13.2 素材详情

详情返回平台保存的最近状态。需要同步最新处理状态时，请调用刷新接口。

13.3 刷新素材状态

该接口不接受请求体或查询参数。

成功返回 200 和更新后的素材对象。建议以合理间隔轮询，直到状态成为 active 或 failed。

素材变成 invalid 时应显式创建新素材，平台不会自动重新上传。

14. 真人认证

真人流程固定为：

创建认证会话
-> 打开 authorization_url 完成真人认证
-> 查询会话直到 completed
-> 获取 LivenessFace 素材组 asset_group_id
-> 将同一真人的图片或视频上传到该素材组
-> 刷新素材直到 active
-> 视频使用 asset://asset_xxx

认证完成只会创建一个已经认证的空素材组，不会自动生成真人图片、视频或音频。

14.1 创建真人认证会话

支持 Idempotency-Key。

成功返回 201：

{
  "id": "authsess_xxx",
  "object": "asset.authorization_session",
  "status": "pending",
  "authorization_url": "https://example.com/authorization/xxx",
  "route_group_id": "g000xx",
  "route_group_name": "Seedance 服务分组展示名称",
  "expires_at": 1783670700,
  "created_at": 1783670400,
  "updated_at": 1783670400
}

客户应在浏览器中打开 authorization_url。该地址具有时效性，不要长期保存或公开分享。

14.2 查询真人认证会话

会话状态：

pending | verifying | completed | failed | expired

认证完成后返回：

{
  "id": "authsess_xxx",
  "object": "asset.authorization_session",
  "status": "completed",
  "asset_group_id": "assetgrp_xxx",
  "route_group_id": "g000xx",
  "route_group_name": "Seedance 服务分组展示名称",
  "expires_at": 1783670700,
  "created_at": 1783670400,
  "updated_at": 1783670600
}

获得 asset_group_id 后，调用普通素材创建接口，把同一真人的素材上传到该组。人脸不一致的素材可能处理失败。

浏览器回调由平台自动处理，客户不需要调用或拼接回调接口。

15. 公域人物

平台公域人物目录由管理员发布和维护，仅展示已经审核并允许公开使用的人物素材。

目录中的人物只在响应所对应的模型和服务分组中可用，不会公开其他客户的私有素材。

15.1 查询公域人物列表

必须传 model。可选参数包括 limit、after、q、tags、gender、age_group 和 nationality。

{
  "object": "list",
  "data": [
    {
      "id": "char_xxx",
      "object": "public_character",
      "name": "business-presenter",
      "preview_url": "https://media.example.com/presenter-preview.jpg",
      "tags": ["business", "presenter"],
      "route_group_id": "g000xx",
      "route_group_name": "Seedance 服务分组展示名称",
      "reference": "asset://char_xxx"
    }
  ],
  "first_id": "char_xxx",
  "last_id": "char_xxx",
  "has_more": false
}

15.2 查询公域人物详情

视频中使用响应里的 reference：

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

当前服务分组没有配置公域人物目录时返回 public_catalog_not_supported。

16. 删除素材和素材组

16.1 删除素材

素材仍被未完成视频任务使用时返回 asset_in_use。成功受理删除时返回 202 和当前素材对象。

16.2 删除素材组

组内仍有未删除素材时返回 asset_group_not_empty。成功受理删除时返回 202 和当前素材组对象。

真人素材组的删除还可能受到认证有效期和使用状态限制。

17. 幂等

以下接口支持 Idempotency-Key：

POST /api/v3/contents/generations/tasks

Seedance 模型的 POST /v1/videos

POST /v1/assets

POST /v1/asset-groups

POST /v1/assets/real-person/authorization-sessions

Key 必须是有效 UTF-8，最长 64 bytes，并且请求中只能出现一次。

相同用户、相同操作、相同 Key和相同请求会返回原资源或原稳定错误。

相同 Key 对应不同请求时返回 409 idempotency_conflict。

原操作仍在竞争或暂时不能重放时返回 409 idempotency_in_progress。

未提供 Key 时不保证跨 HTTP 请求去重。

18. 计费与 usage

视频任务按照可信 usage 及平台当前模型、分辨率、参考视频和分组倍率配置结算。素材、素材组和真人认证的创建、查询、刷新不单独扣除视频额度。

平台可能在任务提交时预扣最大额度，任务取得可信终态后再进行最终结算。客户应以 AnyRoute 价格页面和账户消费记录为准。

成功任务可能返回：

{
  "usage": {
    "completion_tokens": 40594,
    "total_tokens": 40594
  }
}

没有可信 usage 时，平台不会在 API 响应中生成估算 usage。

19. 错误格式

{
  "error": {
    "message": "asset is not ready",
    "type": "asset_not_ready",
    "code": "asset_not_ready"
  }
}

客户端应优先判断稳定的 error.code，不要依赖 message 文案。

HTTP	`code`	含义
400	`invalid_request`	JSON、字段、参数范围或 URL 不合法
400	`invalid_asset_reference`	非法 `asset://` 引用或使用了非平台资源 ID
400	`asset_kind_mismatch`	素材类型与 content 类型不匹配
400	`unsupported_video_parameter`	当前模型不支持该字段、role、分辨率或组合
400	`public_catalog_not_supported`	当前模型未配置平台公域人物目录
400	`task_cancel_not_supported`	当前模型不支持取消排队任务
404	`task_not_found`	任务不存在或不属于当前用户
404	`asset_not_found`	素材不存在或不属于当前用户
404	`asset_group_not_found`	素材组不存在或不属于当前用户
404	`authorization_session_not_found`	真人认证会话不存在或不可访问
404	`public_character_not_found`	公域人物不存在或当前模型不可用
409	`idempotency_conflict`	同一个幂等 Key 对应不同请求
409	`idempotency_in_progress`	幂等操作尚不能安全重放
409	`asset_not_ready`	素材尚未达到 `active`
409	`asset_in_use`	素材正在被未完成任务使用
409	`asset_group_not_empty`	素材组中仍有素材
409	`asset_binding_conflict`	请求中的素材不能组合使用
409	`asset_channel_mismatch`	视频模型与素材不匹配
409	`asset_binding_unavailable`	素材当前不可用
409	`asset_route_group_unavailable`	当前 Token 没有可用的模型服务分组
409	`asset_route_group_misconfigured`	当前服务分组配置不可用
409/410	`asset_invalid`	素材已经失效
410	`authorization_session_expired`	真人认证会话已经过期
410	`video_result_expired`	视频结果已过期且无法刷新
502/503	`asset_upstream_unavailable`	素材服务暂时不可用

20. 推荐调用流程

20.1 普通私有素材视频

1. POST /v1/asset-groups
2. 保存 assetgrp_xxx
3. POST /v1/assets，并传入 group_id
4. 保存 asset_xxx
5. POST /v1/assets/{asset_id}/refresh，直到 active
6. POST /api/v3/contents/generations/tasks
7. 在 content 中使用 asset://asset_xxx
8. GET /api/v3/contents/generations/tasks/{task_id}
9. succeeded 后访问 /v1/videos/{task_id}/content

20.2 真人素材视频

1. POST /v1/assets/real-person/authorization-sessions
2. 打开 authorization_url 完成认证
3. GET 认证会话，直到 completed
4. 保存 asset_group_id
5. POST /v1/assets，把同一真人素材上传到该组
6. POST /v1/assets/{asset_id}/refresh，直到 active
7. POST /api/v3/contents/generations/tasks
8. 在 content 中使用 asset://asset_xxx
9. 查询任务并读取视频结果

20.3 无私有素材的视频

普通商品、场景等符合当前模型输入规则的内容，可以直接在视频请求中使用公网 HTTPS URL或受支持的 Base64 Data URL，不需要先创建平台素材。

1. 基础信息#

1.1 Base URL#

1.2 鉴权#

1.3 资源 ID#

2. 模型和能力#

2.1 已支持的视频输入#

2.2 Base64 图片#

2.3 Base64 音频#

2.4 视频参数#

3. 创建视频任务#

3.1 文生视频#

3.2 公网图片生成视频#

3.3 私有素材生成视频#

3.4 首尾帧#

3.5 参考视频#

3.6 图片加参考音频#

3.7 创建响应#

4. 查询视频任务#

5. 查询任务列表#

6. 获取视频和尾帧#

6.1 获取视频#

6.2 获取尾帧#

7. 删除视频任务#

8. 视频任务回调#

9. /v1/videos 兼容接口#

10. 创建普通素材组#

11. 查询素材组#

11.1 素材组列表#

11.2 素材组详情#

12. 创建私有素材#

13. 查询和刷新素材#

13.1 素材列表#

13.2 素材详情#

13.3 刷新素材状态#

14. 真人认证#

14.1 创建真人认证会话#

14.2 查询真人认证会话#

15. 公域人物#

15.1 查询公域人物列表#

15.2 查询公域人物详情#

16. 删除素材和素材组#

16.1 删除素材#

16.2 删除素材组#

17. 幂等#

18. 计费与 usage#

19. 错误格式#

20. 推荐调用流程#

20.1 普通私有素材视频#

20.2 真人素材视频#

20.3 无私有素材的视频#