虚拟素材库接口文档

本文档用于对接虚拟素材库提供的虚拟资产接口，当前开放以下三类能力：

创建资产：POST /virtual/assets/create

查询资产详情：POST /virtual/assets/detail

删除资产：POST /virtual/assets/delete

接口采用 HTTP + JSON 协议。

1. 接口概览

接口	方法	路径
创建资产	`POST`	`/virtual/assets/create`
资产详情	`POST`	`/virtual/assets/detail`
删除资产	`POST`	`/virtual/assets/delete`

2. 鉴权说明

所有接口都需要传 API Key。

推荐请求头：

同时兼容以下请求头：

x-api-key

api-key

apikey

api_key

x-auth-token

authorization

如果未传 API Key，会返回 401。

如果 API Key 无效，会返回 403。

3. 资产组路由说明

所有接口都必须传请求头 group_id。

group_id 的含义：

由运营人员提供

4. 成功响应说明

创建资产、资产详情两个接口在成功时都返回统一结构：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "asset_xxx",
    "name": "主播头像A",
    "url": "https://example.com/avatar.png",
    "assetType": "Image",
    "status": "Active",
    "groupId": "123456789",
    "projectName": "avatar-demo",
    "errorCode": null,
    "errorMessage": null,
    "createTime": "2026-05-15T13:00:00Z",
    "updateTime": "2026-05-15T13:05:00Z"
  }
}

字段说明：

字段	类型	说明
`code`	integer	业务状态码，成功固定为 `200`
`msg`	string	响应消息
`data.id`	string	资产 ID
`data.name`	string	资产名称
`data.url`	string	资源地址
`data.assetType`	string	资产类型
`data.status`	string	资产统一状态，取值见下方“资产状态说明”
`data.groupId`	string	本地资产组主键
`data.projectName`	string	项目名称
`data.errorCode`	string	厂商错误码，正常情况下为空
`data.errorMessage`	string	厂商错误消息，正常情况下为空
`data.createTime`	string	创建时间
`data.updateTime`	string	更新时间

资产状态说明：

状态值	说明
`Processing`	处理中。通常表示资产仍在上游处理、审核或状态暂未明确时返回该值
`Active`	可用。表示资产已处理完成，可正常使用
`Failed`	失败。表示资产处理失败、审核未通过，或上游已返回明确错误信息

5. 错误响应说明

接口在失败时统一返回标准结构：

{
  "code": 400,
  "msg": "错误消息",
  "data": {
    "code": "VID-4001",
    "message": "错误消息",
    "retryable": false,
    "requestId": null,
    "provider": "byteplus",
    "path": "/virtual/assets/create"
  }
}

字段说明：

字段	类型	说明
`code`	integer	HTTP 状态码
`msg`	string	错误消息
`data.code`	string	业务错误码
`data.message`	string	详细错误消息
`data.retryable`	boolean	是否建议重试
`data.requestId`	string	上游请求 ID，可能为空
`data.provider`	string	厂商标识，可能为 `local`、`byteplus`、`zlhub`
`data.path`	string	当前请求路径

常见错误码：

业务错误码	HTTP 状态码	说明
`VID-4010`	`401`	缺少 API Key
`VID-4030`	`403`	API Key 无效
`VID-4001`	`400`	参数校验失败，例如缺少 `group_id`、缺少必要请求字段、资产组不存在
`VID-5003`	`500`	上游响应无法解析

6. 创建资产

6.1 接口信息

方法：POST

路径：/virtual/assets/create

Content-Type：application/json

6.2 请求头

请求头	必填	说明
`Authorization`	是	API Key，推荐 `Bearer sk-xxxxxx`
`group_id`	是	本地资产组主键
`Content-Type`	是	固定为 `application/json`

6.3 请求体说明

请求体必须是合法 JSON 对象，对外统一字段如下：

字段	类型	必填	说明
`url`	string	是	资源地址
`name`	string	否	资产名称
`assetType`	string	否	资产类型，不传时默认 `Image`

6.4 请求示例

通用示例

6.5 成功响应示例

成功响应为统一 DTO，以下为示意：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "asset_xxx",
    "name": "头像A",
    "url": "https://example.com/avatar.png",
    "assetType": "Image",
    "status": "Active",
    "groupId": "123456789",
    "projectName": "avatar-demo",
    "errorCode": null,
    "errorMessage": null,
    "createTime": "2026-05-15T13:00:00Z",
    "updateTime": "2026-05-15T13:05:00Z"
  }
}

7. 资产详情

7.1 接口信息

方法：POST

路径：/virtual/assets/detail

Content-Type：application/json

7.2 请求头

请求头	必填	说明
`Authorization`	是	API Key，推荐 `Bearer sk-xxxxxx`
`group_id`	是	本地资产组主键
`Content-Type`	是	固定为 `application/json`

7.3 请求体说明

请求体必须是合法 JSON 对象，对外统一字段如下：

字段	类型	必填	说明
`assetId`	string	是	统一资产标识

7.4 请求示例

通用示例

7.5 成功响应示例

以下为示意：

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "asset_xxx",
    "name": "主播头像A",
    "url": "https://example.com/avatar.png",
    "assetType": "Image",
    "status": "Active",
    "groupId": "123456789",
    "projectName": "avatar-demo",
    "errorCode": null,
    "errorMessage": null,
    "createTime": "2026-05-15T13:00:00Z",
    "updateTime": "2026-05-15T13:05:00Z"
  }
}

8. 删除资产

8.1 接口信息

方法：POST

路径：/virtual/assets/delete

Content-Type：application/json

8.2 请求头

请求头	必填	说明
`Authorization`	是	API Key，推荐 `Bearer sk-xxxxxx`
`group_id`	是	本地资产组主键
`Content-Type`	是	固定为 `application/json`

8.3 请求体说明

请求体必须是合法 JSON 对象，对外统一字段如下：

字段	类型	必填	说明
`assetId`	string	是	统一资产标识
`projectName`	string	否	项目名称，不传时默认回退到资产组绑定的项目

8.4 请求示例

通用示例

8.5 响应说明

结构：

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

字段说明：

字段	类型	说明
`code`	integer	业务状态码，固定为 `200`
`msg`	string	响应消息，失败时返回具体失败原因
`data`	boolean	删除结果，`true` 表示删除成功，`false` 表示删除失败

8.6 响应示例

删除成功

{
  "code": 200,
  "msg": "操作成功",
  "data": true
}

资产不存在

{
  "code": 200,
  "msg": "资产不存在",
  "data": false
}

删除失败

{
  "code": 200,
  "msg": "具体失败原因",
  "data": false
}

9. 对接建议

请始终保存并传递正确的 group_id

Seedance虚拟素材库接口文档

虚拟素材库接口文档#

1. 接口概览#

2. 鉴权说明#

3. 资产组路由说明#

4. 成功响应说明#

5. 错误响应说明#

6. 创建资产#

6.1 接口信息#

6.2 请求头#

6.3 请求体说明#

6.4 请求示例#

通用示例#

6.5 成功响应示例#

7. 资产详情#

7.1 接口信息#

7.2 请求头#

7.3 请求体说明#

7.4 请求示例#

通用示例#

7.5 成功响应示例#

8. 删除资产#

8.1 接口信息#

8.2 请求头#

8.3 请求体说明#

8.4 请求示例#

通用示例#

8.5 响应说明#

8.6 响应示例#

删除成功#

资产不存在#

删除失败#

9. 对接建议#

虚拟素材库接口文档

1. 接口概览

2. 鉴权说明

3. 资产组路由说明

4. 成功响应说明

5. 错误响应说明

6. 创建资产

6.1 接口信息

6.2 请求头

6.3 请求体说明

6.4 请求示例

通用示例

6.5 成功响应示例

7. 资产详情

7.1 接口信息

7.2 请求头

7.3 请求体说明

7.4 请求示例

通用示例

7.5 成功响应示例

8. 删除资产

8.1 接口信息

8.2 请求头

8.3 请求体说明

8.4 请求示例

通用示例

8.5 响应说明

8.6 响应示例

删除成功

资产不存在

删除失败

9. 对接建议