Seedance 海外线路 - 1 & 2

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

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

1. 基础信息

1.1 Base URL

https://biz.anyroute.io

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

1.2 鉴权

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

发送 JSON 时还需要：

客户只使用 AnyRoute API Token 进行鉴权。

1.3 资源 ID

平台返回以下不透明资源 ID：

task_xxx      视频任务
asset_xxx     私有素材
assetgrp_xxx  客户素材组
char_xxx      公域人物

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

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

2. 模型与素材模式

当前公开模型分为普通/EP 和 HC 两种素材模式。视频接口相同，区别仅在创建私有素材时是否需要客户素材组。

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

2.1 普通/EP 模型

dreamina-seedance-2-0-260128
dreamina-seedance-2-0-ep
dreamina-seedance-2-0-fast-260128
dreamina-seedance-2-0-fast-ep
dreamina-seedance-2-0-mini-260615
dreamina-seedance-2-0-mini-ep

普通/EP 模型的私有素材流程：

创建素材组 -> 创建素材并传入 group_id -> 刷新到 active -> 视频使用 asset://asset_xxx

素材和素材组对象会返回当前服务分组的对外展示名称。展示名称可能由管理员调整，客户不需要填写该名称来选择服务分组。

2.2 HC 模型

dreamina-seedance-2-0-fast-hc
dreamina-seedance-2-0-hc
dreamina-seedance-2-0-mini-hc

HC 模型的私有素材流程：

直接创建素材，不传 group_id -> 刷新到 active -> 视频使用 asset://asset_xxx

2.3 素材不能跨模式使用

普通/EP 与 HC 使用不同的素材空间：

普通/EP 素材不能用于 HC 模型。

HC 素材不能用于普通/EP 模型。

同一个视频任务不能混用两种素材空间的素材。

素材与创建时的模型类型固定关联，不会自动迁移到另一种素材模式或在失败后重新创建。

交叉使用会在创建视频任务前返回明确错误，例如 asset_channel_mismatch 或 asset_binding_conflict。

3. 视频输入能力

主要视频入口为：

3.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。

图片 Data URL 示例：

data:image/jpeg;base64,<BASE64_DATA>

允许 jpeg、png、webp、bmp、tiff、gif，格式名必须小写。单张图片解码后必须小于 30 MB。

音频 Data URL 示例：

data:audio/mpeg;base64,<BASE64_DATA>

允许 wav、mp3、mpeg。单段音频不超过 15 MB，最多 3 段。参考音频不能作为唯一参考输入，必须同时提供至少一张参考图片或一个参考视频。

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

3.2 支持的视频参数

字段	类型	说明
`model`	string	必填，公开模型名称
`content`	array	必填，1-64 项
`duration`	integer	可选，4-15 秒
`resolution`	string	可选，以当前模型能力为准
`ratio`	string	可选，以当前模型能力为准
`generate_audio`	boolean	可选，是否生成音频
`watermark`	boolean	可选，是否添加水印
`return_last_frame`	boolean	可选，是否返回尾帧
`callback_url`	string	可选，接收平台任务回调的公网 HTTPS URL

当前模型不支持 frames、seed、camera_fixed、service_tier、execution_expires_after、priority、draft 和 tools。提交未支持的字段会返回 unsupported_video_parameter，不会静默丢弃字段。

duration 只接受 4-15 秒内的整数，不支持 -1。resolution 和 ratio 的具体可用值以公开模型能力及接口校验结果为准；布尔参数会保留显式传入的 false。

请求使用严格 JSON 校验。未知字段返回 400 invalid_request。

4. 创建视频任务

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

4.1 文生视频

4.2 公网图片生成视频

适用于普通商品、场景等可以直接使用公网地址的素材：

4.3 私有素材生成视频

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

HC 素材的引用格式完全相同，只需使用与该素材匹配的 HC 模型。

4.4 首尾帧

{
  "model": "dreamina-seedance-2-0-260128",
  "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
}

4.5 参考视频

{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考视频中的动作节奏，保持画面稳定"
    },
    {
      "type": "video_url",
      "video_url": {"url": "asset://asset_xxx"},
      "role": "reference_video"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9"
}

4.6 图片加参考音频

{
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考人物和音频生成自然讲述视频"
    },
    {
      "type": "image_url",
      "image_url": {"url": "asset://asset_xxx"},
      "role": "reference_image"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://media.example.com/voice.mp3"},
      "role": "reference_audio"
    }
  ],
  "duration": 4,
  "resolution": "480p",
  "ratio": "16:9",
  "generate_audio": true
}

4.7 创建响应

提交结果确定时返回 200：

{
  "id": "task_xxx"
}

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

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

5. 查询视频任务

成功响应：

{
  "id": "task_xxx",
  "model": "dreamina-seedance-2-0-260128",
  "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",
  "generate_audio": false,
  "watermark": false,
  "return_last_frame": true
}

平台状态固定为：

queued | running | cancelled | succeeded | failed | expired

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

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

6. 查询视频任务列表

查询参数：

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

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

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

7. 获取视频和尾帧

7.1 获取视频

7.2 获取尾帧

仅当任务实际生成尾帧时可用：

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

8. 视频任务回调

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

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

{
  "event_id": "evt_xxx",
  "type": "succeeded",
  "created_at": 1783670580,
  "data": {
    "id": "task_xxx",
    "model": "dreamina-seedance-2-0-260128",
    "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>

签名密钥由创建任务使用的 API Token 通过 HKDF-SHA256 派生，info 为 new-api-video-callback-v1，无 salt。签名内容为：

timestamp + "\n" + event_id + "\n" + raw_request_body

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

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

创建示例：

V1 和 V3 共用同一个任务系统。V1 创建的任务可以使用 V3 查询，V3 创建的任务也可以使用 V1 查询。

V1 同样只接受 JSON，不支持 Multipart。

10. 创建普通/EP 素材组

该接口只用于普通/EP 模型。HC 模型不创建素材组。

支持 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 普通/EP 分组展示名称",
  "created_at": 1783670400,
  "updated_at": 1783670400
}

route_group_name 是当前服务分组的对外展示名称。客户业务应保存 assetgrp_xxx，并在后续创建普通/EP 素材时将其作为 group_id。

客户只能创建 group_type: "AIGC"。当前模型不提供独立真人 H5 授权或 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

12.1 普通/EP 素材

普通/EP 模型必须传入已经创建的 assetgrp_xxx：

缺少 group_id 时返回 400 invalid_request。

12.2 HC 素材

HC 模型不传 group_id：

12.3 创建响应

创建返回 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 普通/EP 分组展示名称",
  "created_at": 1783670400,
  "updated_at": 1783670400
}

HC 素材响应不包含 group_id，并返回 HC 服务分组的当前对外展示名称。

素材状态：

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

只有 active 素材可以用于视频。processing 不代表失败，应调用刷新接口查询最终状态。

13. 查询私有素材

13.1 素材列表

支持以下查询参数：

参数	说明
`limit`	默认 20，范围 1-100
`after`	上一页返回的 `last_id`
`status`	素材状态
`asset_type`	`Image`、`Video`、`Audio`
`group_id`	普通/EP 客户素材组 ID
`route_group_id`	按服务分组筛选；通常不需要填写

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

列表来自平台本地数据库，只返回当前用户自己的素材。

13.2 素材详情

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

14. 刷新素材状态

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

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

素材变成 invalid 时应显式创建新素材。平台不会自动重新上传或复制到另一种素材模式。

15. 真人素材

当前模型没有独立的真人 H5 活体授权接口。真人图片或视频按普通私有素材流程提交审核：

根据模型选择普通/EP或 HC 流程
-> 创建私有素材
-> 刷新到 active
-> 视频使用 asset://asset_xxx

客户必须确保拥有真人素材及生成用途所需的合法授权。

含真人身份特征的图片或视频建议使用审核通过的 asset://。平台不会在提交前做人脸识别；直接使用公网 URL 或 Base64 不符合当前模型规则时，任务会按正常异步失败返回。

调用真人授权会话接口会返回：

real_person_auth_not_supported

16. 公域人物

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

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

16.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 普通/EP 分组展示名称",
      "reference": "asset://char_xxx"
    }
  ],
  "first_id": "char_xxx",
  "last_id": "char_xxx",
  "has_more": false
}

16.2 查询公域人物详情

视频中使用响应里的 reference：

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

如果当前模型没有配置可用公域人物目录，返回 public_catalog_not_supported。

17. 幂等

以下接口支持 Idempotency-Key：

POST /api/v3/contents/generations/tasks

Seedance 模型的 POST /v1/videos

POST /v1/assets

POST /v1/asset-groups

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. 当前不支持的操作

操作	结果
`DELETE /api/v3/contents/generations/tasks/{task_id}`	`task_cancel_not_supported` 或 `task_delete_not_supported`
`DELETE /v1/assets/{asset_id}`	`asset_delete_not_supported`
`DELETE /v1/asset-groups/{group_id}`	`asset_group_delete_not_supported`
创建真人授权会话	`real_person_auth_not_supported`
HC 模型创建素材组	`asset_groups_not_supported`

不支持的操作会直接返回明确错误，现有资源状态保持不变。

20. 错误格式

统一错误响应：

{
  "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	`asset_groups_not_supported`	当前模型不支持素材组
400	`unsupported_video_parameter`	当前模型不支持该视频字段、role 或组合
400	`asset_delete_not_supported`	当前模型不支持删除素材
400	`asset_group_delete_not_supported`	当前模型不支持删除素材组
400	`real_person_auth_not_supported`	当前模型没有真人 H5 授权接口
400	`public_catalog_not_supported`	当前模型未配置平台公域人物目录
404	`task_not_found`	任务不存在或不属于当前用户
404	`asset_not_found`	素材不存在或不属于当前用户
404	`asset_group_not_found`	素材组不存在或不属于当前用户
404	`public_character_not_found`	公域人物不存在或当前模型不可用
409	`idempotency_conflict`	同一个幂等 Key 对应不同请求
409	`idempotency_in_progress`	幂等操作尚不能安全重放
409	`asset_not_ready`	素材尚未达到 `active`
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	`video_result_expired`	视频结果已过期且无法刷新
502/503	`asset_upstream_unavailable`	素材服务暂时不可用

21. 推荐调用流程

21.1 普通/EP 私有素材视频

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

21.2 HC 私有素材视频

1. POST /v1/assets，不传 group_id
2. 保存 asset_xxx
3. POST /v1/assets/{asset_id}/refresh，直到 active
4. POST /api/v3/contents/generations/tasks，并使用对应 HC 模型
5. 在 content 中使用 asset://asset_xxx
6. GET /api/v3/contents/generations/tasks/{task_id}
7. succeeded 后访问 /v1/videos/{task_id}/content

21.3 无私有素材的视频

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

真人身份、私有角色以及需要稳定复用的图片、视频和音频，建议先进入与目标模型匹配的私有素材流程。

Seedance 海外线路 - 1 & 2

1. 基础信息#

1.1 Base URL#

1.2 鉴权#

1.3 资源 ID#

2. 模型与素材模式#

2.1 普通/EP 模型#

2.2 HC 模型#

2.3 素材不能跨模式使用#

3. 视频输入能力#

3.1 支持的内容类型#

3.2 支持的视频参数#

4. 创建视频任务#

4.1 文生视频#

4.2 公网图片生成视频#

4.3 私有素材生成视频#

4.4 首尾帧#

4.5 参考视频#

4.6 图片加参考音频#

4.7 创建响应#

5. 查询视频任务#

6. 查询视频任务列表#

7. 获取视频和尾帧#

7.1 获取视频#

7.2 获取尾帧#

8. 视频任务回调#

9. /v1/videos 兼容接口#

10. 创建普通/EP 素材组#

11. 查询素材组#

11.1 素材组列表#

11.2 素材组详情#

12. 创建私有素材#

12.1 普通/EP 素材#

12.2 HC 素材#

12.3 创建响应#

13. 查询私有素材#

13.1 素材列表#

13.2 素材详情#

14. 刷新素材状态#

15. 真人素材#

16. 公域人物#

16.1 查询公域人物列表#

16.2 查询公域人物详情#

17. 幂等#

18. 计费与 usage#

19. 当前不支持的操作#

20. 错误格式#

21. 推荐调用流程#

21.1 普通/EP 私有素材视频#

21.2 HC 私有素材视频#

21.3 无私有素材的视频#