Seedance 2.0 - 素材库（数字人素材管理接口）

面向业务接入方的数字人素材管理接口，提供真人形象与虚拟形象素材的创建、上传、查询、状态同步与删除能力。

---

0. 鉴权与约定

• 认证方式：Authorization: Bearer {new-api-token}
• 数据格式：除特别说明外，均使用 application/json
• 通用响应：大多数接口返回：
• success: boolean
• message: string（可为空）
• data: object | null

---

1. 概念说明

1.1 素材容器（Group）

素材容器用于承载一组素材文件（图片/视频/音频等）。

• group_type
• 1：真人形象（LivenessFace）——需要走人脸核验流程创建
• 2：虚拟形象（AIGC）——直接创建容器后上传素材

1.2 素材文件（Asset）

素材文件为容器下的叶子节点。上传成功后状态通常先为 Processing(0)，需要轮询查询接口直到 Active(1) 或 Failed(2)。

---

2. 数据结构

2.1 UserAssetResponse

素材/素材容器统一响应体（关键字段）：

• id：资源唯一标识（resource_id）
• asset_type：素材类型
• 0：未知
• 1：素材容器
• 2：视频素材
• 3：图片素材
• 4：音频素材
• group_type：素材容器类型（0/1/2）
• name / description
• status：素材状态
• 0：处理中
• 1：可用
• 2：失败（可结合 fail_reason）
• is_leaf
• 0：素材容器
• 1：素材文件
• created_at / updated_at：Unix 时间戳（秒）

---

3. 真人形象（GroupType=1 / LivenessFace）

3.1 创建真人形象核验会话

• POST /v1/asset/human/session
• 用途：创建真人形象核验会话，返回核验页面链接。用户完成核验后会跳转到你传入的 redirect_url，并携带结果参数：
• 成功：status=success&group_id={groupId}
• 失败：status=failed&reason={reason}

请求体

必填：redirect_url

{
  "name": "张三的真人形象",
  "description": "用于数字人视频生成",
  "redirect_url": "https://your-app.com/asset/callback-result"
}

响应示例

{
  "success": true,
  "data": {
    "Url": "https://xxx.volccdn.com/verify?token=xxx",
    "H5Link": "https://xxx.volccdn.com/verify?token=xxx",
    "BytedToken": "byted_token_abc123"
  }
}

---

4. 虚拟形象（GroupType=2 / AIGC）

4.1 创建虚拟形象素材容器

• POST /v1/asset/human/aigc
• 用途：创建虚拟形象素材容器，返回 GroupId，后续可向该容器上传素材。

请求体

必填：name

{
  "name": "虚拟主播A",
  "description": "用于直播带货场景的 AIGC 素材"
}

响应示例

{
  "success": true,
  "data": {
    "GroupId": "group_abc123"
  }
}

---

5. 素材通用（列表 / 状态同步 / 更新 / 删除）

5.1 上传素材文件

• POST /v1/asset/human/upload
• 用途：向指定素材容器上传一个素材文件（图片、视频、音频）。
• 注意：
• 上传后素材状态为 Processing(0)，需要轮询查询接口直到 Active(1) 或 Failed(2)
• group_id 必须属于当前 Token 对应的用户

请求体

必填：group_id、url、asset_type

asset_type 枚举： - Image - Video - TrainingVideo - Script - Audio

{
  "group_id": "group_abc123",
  "url": "https://cdn.example.com/video/demo.mp4",
  "asset_type": "Video",
  "name": "演示视频",
  "description": "用于数字人视频生成"
}

响应示例

data 为 UserAssetResponse（初始状态一般为 Processing）。

{
  "success": true,
  "message": "",
  "data": {
    "id": "asset_xyz789",
    "asset_type": 2,
    "group_type": 1,
    "name": "演示视频",
    "description": "用于数字人视频生成",
    "status": 0,
    "fail_reason": "",
    "is_leaf": 1,
    "created_at": 1714000000,
    "updated_at": 1714000000
  }
}

5.2 获取素材列表

• GET /v1/asset/human/list
• 用途：查询当前用户素材列表，支持按 group_id 过滤。
• 参数：
• group_id（可选）：按素材容器过滤
• is_leaf（可选）：1 只返回素材文件（默认）；0 返回素材容器
• p（可选）：页码（默认 1）
• page_size（可选）：每页条数（默认 20）

请求示例

curl "https://api.agtcloud.ai/v1/asset/human/list?group_id=group_abc123&is_leaf=1&p=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

响应示例

{
  "success": true,
  "data": {
    "total": 5,
    "items": [
      {
        "id": "asset_xyz789",
        "asset_type": 2,
        "group_type": 1,
        "name": "演示视频",
        "description": "用于数字人视频生成",
        "status": 1,
        "fail_reason": "",
        "is_leaf": 1,
        "created_at": 1714000000,
        "updated_at": 1714001000
      }
    ]
  }
}

5.3 同步素材状态（轮询）

• GET /v1/asset/human/get/{id}
• 用途：查询并同步单个素材的最新状态；适用于上传后轮询等待 Active(1)。
• 路径参数：
• id：素材的 resource_id（即返回结果中的 id）

请求示例

curl "https://api.agtcloud.ai/v1/asset/human/get/asset_xyz789" \
  -H "Authorization: Bearer $API_KEY"

5.4 更新素材信息

• PUT /v1/asset/human/update/{id}
• 用途：更新素材的名称或描述。

请求体示例

{
  "name": "更新后的演示视频",
  "description": "新描述"
}

5.5 删除素材或素材容器

• DELETE /v1/asset/human/delete/{id}
• 用途：删除素材或素材容器。
• 行为区分（由被删除资源的 is_leaf 决定）：
• is_leaf=0（素材容器）：删除容器及容器内所有素材
• is_leaf=1（素材文件）：删除单个素材

请求示例

curl -X DELETE "https://api.agtcloud.ai/v1/asset/human/delete/group_abc123" \
  -H "Authorization: Bearer $API_KEY"