Asset API

Seedance 2.0 个人素材 API

1. 文档基础信息

配置项	参数内容
基础请求域名	https://mjlm.coral-gpu.com/
全局鉴权方式	API令牌鉴权（sk-xxx格式）
统一请求头	Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx
文档用途	漫剧联盟个人素材模块接口调用、开发对接

2. 接口总览

本模块共提供13个个人素材管理接口，涵盖素材上传、查询、删除、详情获取全流程，所有接口基于用户Token实现数据隔离，仅可操作当前账号所属素材。

接口名称	请求方式	接口路径	核心功能说明
创建个人素材分组	POST	/v1/assets/asset-groups	创建个人素材分组，用于后续组织管理个人素材，归属当前Token用户
查询个人素材分组详情	GET	/v1/assets/asset-groups/:groupId	基于分组ID查询个人素材分组信息，归属当前Token用户
修改个人素材分组	PUT	/v1/assets/asset-groups/:groupId	基于分组ID修改个人素材分组名称，归属当前Token用户
删除个人素材分组	DELETE	/v1/assets/asset-groups/:groupId	基于分组ID删除个人素材分组，归属当前Token用户
查询个人素材分组分页列表	POST	/v1/assets/asset-groups/query	用于查询个人拥有的素材分组列表，归属当前Token用户
上传个人素材（本地文件）	POST	/v1/assets/asset/upload	上传本地图片、视频、音频文件，归属当前Token用户
上传个人素材（在线链接）	POST	/v1/assets/asset/upload-url	通过公开在线资源链接上传素材，归属当前Token用户
查询个人素材详情	GET	/v1/assets/asset/:asset_id	查询指定素材的完整详情信息，归属当前Token用户
修改个人素材信息	PUT	/v1/assets/asset/:asset_id	根据素材ID修改个人素材名称，归属当前Token用户
删除个人素材	DELETE	/v1/assets/asset/:asset_id	根据素材ID删除指定素材，归属当前Token用户
查询个人素材列表	POST	/v1/assets/asset/query	分页查询当前用户名下所有个人素材，归属当前Token用户
创建H5认证（真人认证）会话	POST	/v1/assets/asset-groups/session	创建真人认证会话，归属当前Token用户
查询真人素材组	POST	/v1/assets/asset-groups/by-byted-token	通过bytedToken查询真人素材组，归属当前Token用户

3. 接口详细参数说明

3.1 创建个人素材分组

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
name	string	否	素材组名称，最长64个字符，非必填
description	string	否	素材组简介，最长300个字符，非必填

请求示例：

JSON

{
"name":"test yidong group",
"description":"go test create material assets group"
}

返回参数：

参数名称	参数类型	描述
groupId	string	火山资产组ID
groupType	enum	AssetGroupTypeEnum
groupName	string	资产组名称
description	string	资产组简介
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"updatedTime": "2026-07-17 15:04:51",
"groupType": "AIGC",
"groupName": "test yidong group",
"groupId": "group-20260717150451-l8rb6",
"description": "go test create material assets group",
"createdTime": "2026-07-17 15:04:51"
}

3.2 查询个人素材分组详情

接口地址：GET https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/:groupId

Path：

参数名	参数类型	是否必填	参数说明
groupId	string	是	素材组ID（火山资产组ID）

请求示例：

TEXT

https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/group-20260717110924-7cjlp

返回参数：

参数名称	参数类型	描述
groupId	string	火山资产组ID
groupType	enum	AssetGroupTypeEnum
groupName	string	资产组名称
description	string	资产组简介
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"updatedTime": "2026-07-17 11:09:24",
"groupType": "AIGC",
"groupName": "test yidong group",
"groupId": "group-20260717110924-7cjlp",
"description": "go test create material assets group",
"createdTime": "2026-07-17 11:09:24"
}

3.3 修改个人素材分组

接口地址：PUT https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/:groupId

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
name	string	否	素材组名称，最长64个字符，非必填
description	string	否	素材组简介，最长300个字符，非必填

请求示例：

JSON

{
"name":"test yidong group200",
"description":"go test create material assets group"
}

返回参数：

参数名称	参数类型	描述
groupId	string	火山资产组ID
groupType	enum	AssetGroupTypeEnum
groupName	string	资产组名称
description	string	资产组简介
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"updatedTime": "2026-07-17 11:05:20",
"groupType": "AIGC",
"groupName": "test yidong group200",
"groupId": "group-20260717105552-h2m5s",
"description": "go test create material assets group",
"createdTime": "2026-07-17 10:55:52"
}

3.4 删除个人素材分组

接口地址：DELETE https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/:groupId

Path：

参数名	参数类型	是否必填	参数说明
groupId	string	是	素材组ID（火山资产组ID）

请求示例：

TEXT

https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/group-20260717110924-7cjlp

返回参数：

参数名称	参数类型	描述
status	boolean	布尔值

返回示例：

JSON

{
"status": "OK"
}

3.5 查询个人素材分组列表

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/query

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
pageNo	integer	否	页码（从 1 开始）
pageSize	integer	否	每页行数
groupType	string	否	素材组类型过滤，可选值：AIGC（虚拟人像素材库）、LivenessFace（真人素材库），不传则不过滤
groupName	string	否	素材组名称模糊搜索关键字，最长64个字符，不传则不过滤
groupIds	<string> array	否	素材组ID列表，按ID精确查询，不传则不过滤

请求示例：

JSON

{
"pageNo":1,
"pageSize":10,
"groupType":"AIGC",
"groupName":"",
"groupIds":[
]
}

返回参数：

参数名称	参数类型	描述
total	integer	查询总条数
data	<AssetGroupDTO> array	分页查询列表
groupId	string	火山资产组ID
groupType	enum	AssetGroupTypeEnum
groupName	string	资产组名称
description	string	资产组简介
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"total": 2,
"data": [
{
"updatedTime": "2026-07-17 11:09:50",
"groupType": "AIGC",
"groupName": "test yidong group",
"groupId": "group-20260717110950-djpv4",
"description": "go test create material assets group",
"createdTime": "2026-07-17 11:09:50"
},
{
"updatedTime": "2026-07-17 11:09:24",
"groupType": "AIGC",
"groupName": "test yidong group",
"groupId": "group-20260717110924-7cjlp",
"description": "go test create material assets group",
"createdTime": "2026-07-17 11:09:24"
}
]
}

3.6 上传个人素材（本地文件）

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset/upload

请求入参（Form-Data）：

参数名	参数类型	是否必填	参数说明
assetName	string	是	素材名称模糊搜索关键字，最长64个字符，不传则不过滤
groupId	string	是	素材组ID列表，按ID精确查询，不传则不过滤
file	stream	是	二进制流

请求示例：

返回参数：

参数名称	参数类型	描述
id	string	火山素材ID

返回示例：

JSON

{
"id": "asset-20260717112309-z75vh"
}

3.7 上传个人素材（在线链接）

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset/upload-url

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
assetType	string	否	素材组类型过滤，可选值：AIGC（虚拟人像素材库）、LivenessFace（真人素材库），不传则不过滤
assetName	string	否	素材名称，最长64个字符
assetUrl	string	否	素材URL，需为公网可访问的HTTP/HTTPS地址，火山侧将通过该URL下载素材
groupId	string	否	素材组ID列表，按ID精确查询，不传则不过滤

素材资产规格：

分类	类型	格式要求	尺寸 / 分辨率	宽高比	像素限制	时长范围	帧率	大小上限
图片素材	Image	jpeg、png、webp、bmp、tiff、gif、heic、heif	单边像素：300px~6000px	0.4＜宽高比＜ 2.5		无时长要求	无	单文件 ≤ 30MB
视频素材	Video	mp4、mov	固定可选：480p、720p、1080p单边像素：300px~6000px	0.4 ≤ 宽高比 ≤ 2.5	总像素（宽 × 高）：409600 ~ 2086876	2s~15s	24 ~ 60 FPS	单文件 ≤ 200MB
音频素材	Audio	wav、mp3	无	无	无	2s~15s	无	单文件 ≤ 15MB

请求示例：

JSON

{
"groupId":"group-20260717110924-7cjlp",
"assetName":"黑色奔跑骏马2",
"assetUrl":"https://mjlm.coral-gpu.com/upload/images/20260706165600_0K597.jpg",
"assetType":"Image"
}

返回参数：

参数名称	参数类型	描述
id	string	火山素材ID

返回示例：

JSON

{
"id": "asset-20260717112309-z75vh"
}

3.8 查询个人素材详情

接口地址：GET https://mjlm.coral-gpu.com:3000/v1/assets/asset/:asset_id

Path：

参数名	参数类型	是否必填	参数说明
assetId	string	是	火山素材ID

请求示例：

TEXT

https://mjlm.coral-gpu.com:3000/v1/assets/asset/asset-20260717112309-z75vh

返回参数：

参数名称	参数类型	描述
assetId	string	火山素材ID
groupId	string	火山资产组ID
assetUrl	string	素材预签名URL，动态生成，有效期12小时
assetType	enum	AssetGroupTypeEnum
assetName	string	资产组名称
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"updatedTime": "2026-07-17 11:51:40",
"assetId": "asset-20260717111353-czmmg",
"groupId": "group-20260717110950-djpv4",
"assetName": "亮黑色帅气奔跑骏马",
"createdTime": "2026-07-17 11:13:53",
"assetUrl": "https://ark-media-asset.tos-cn-beijing.volces.com/2125187037/071711135357575406.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKTP0VyX37NH37peqQWqz0vNmCyOZWlZ317MWKcRRWrqoq%2F20260717%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260717T073235Z&X-Tos-Expires=43200&X-Tos-Security-Token=nChBSRDZTall6QTdZRVN1cm9C.CiQKEEZwNVZqRjExMmozQUV4aUQSEBV7NjHviEvUuoHQ3TsUWNgQzb3m0gYYso7p0gYg-v3I6QcoBDCs7-stOh9Sb2xlRm9yQXJrQXNzZXQvUm9sZUZvckFya0Fzc2V0QgNhcmtSD1JvbGVGb3JBcmtBc3NldFgDegNhcms.Q2kzjuA4Y5bEmSxvSdaNIgsFkCOnXfLynKC-MRiecl7EGTO-2jIYfKWyrc5596g-DeVHXADfWkZzsN8I5GBiQQ&X-Tos-Signature=5fa88162e0b0ca447b37bae10e62f29a6cb5d360d434247bedfdc6ed5b56f70d&X-Tos-SignedHeaders=host",
"assetType": "Image",
"status": "ACTIVE"
}

3.9 修改个人素材

接口地址：PUT https://mjlm.coral-gpu.com:3000/v1/assets/asset/:asset_id

Path：

参数名	参数类型	是否必填	参数说明
assetId	string	是	火山素材ID

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
assetName	string	否	素材名称，最长64个字符，不传则不更新

请求示例：

JSON

{
"assetName":"亮黑色帅气奔跑骏马"
}

返回参数：

参数名称	参数类型	描述
assetId	string	火山素材ID
groupId	string	火山资产组ID
assetUrl	string	素材预签名URL，动态生成，有效期12小时
assetType	enum	AssetGroupTypeEnum
assetName	string	资产组名称
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss

返回示例：

JSON

{
"updatedTime": "2026-07-17 11:51:40",
"assetId": "asset-20260717111353-czmmg",
"groupId": "group-20260717110950-djpv4",
"assetName": "亮黑色帅气奔跑骏马",
"createdTime": "2026-07-17 11:13:54",
"assetUrl": "https://ark-media-asset.tos-cn-beijing.volces.com/2125187037/071711135357575406.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKTP0VyX37NH37peqQWqz0vNoyhchXO7jXKuBGuqXj22Dk%2F20260717%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260717T035140Z&X-Tos-Expires=43200&X-Tos-Security-Token=nChBSRDZTall6QTdZRVN1cm9C.CiQKEEZwNVZqRjExMmozQUV4aUQSEHB9PP2zl0C6jwA6zF137PwQ877m0gYYrI_p0gYg-v3I6QcoBDCs7-stOh9Sb2xlRm9yQXJrQXNzZXQvUm9sZUZvckFya0Fzc2V0QgNhcmtSD1JvbGVGb3JBcmtBc3NldFgDegNhcms.Yhiu1ifMqWNraImeTjZ1pGID3R6tW1u_lJhxLU9OCJUwqe2TSHplXmp_b1pkFDOtVpGkDL_-NHqOix1gpOVuEA&X-Tos-Signature=036b61e1e23bca3f8c3282a817bb0ed76c034aaf9b5b1b9b12977c7e92afbbd3&X-Tos-SignedHeaders=host",
"assetType": "Image",
"status": "ACTIVE"
}

3.10 删除个人素材

接口地址：DELETE https://mjlm.coral-gpu.com:3000/v1/assets/asset/:asset_id

Path：

参数名	参数类型	是否必填	参数说明
assetId	string	是	火山素材ID

请求示例：

TEXT

https://mjlm.coral-gpu.com:3000/v1/assets/asset/asset-20260717112309-z75vh

返回参数：

参数名称	参数类型	描述
status	boolean	布尔值

返回示例：

JSON

{
"status": true
}

3.11 查询个人素材列表

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset/query

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
pageNo	integer	否	页码（从 1 开始）
pageSize	integer	否	每页行数
groupIds	<string> array	否	素材组ID列表，按分组筛选素材，不传则查询当前用户所有素材

请求示例：

JSON

{
"pageNo": 1,
"pageSize": 10,
"groupIds": [
"group-20260717110950-djpv4"
]
}

返回参数：

参数名称	参数类型	描述
total	integer	查询总条数
data	<AssetDTO> array	分页查询列表
groupId	string	火山资产组ID
assetId	string	火山素材ID
assetType	enum	AssetTypeEnum
assetName	string	素材名称
assetUrl	string	素材预签名URL，动态生成，有效期12小时
createdTime	string(date-time)	创建时间，格式：yyyy-MM-dd HH:mm:ss
updatedTime	string(date-time)	更新时间，格式：yyyy-MM-dd HH:mm:ss
status	enum(PROCESSING,ACTIVE,FAILED)	AssetStatusEnum

返回示例：

JSON

{
"total": 1,
"data": [
{
"updatedTime": "2026-07-17 11:51:40",
"assetId": "asset-20260717111353-czmmg",
"groupId": "group-20260717110950-djpv4",
"assetName": "亮黑色帅气奔跑骏马",
"createdTime": "2026-07-17 11:13:53",
"assetUrl": "https://ark-media-asset.tos-cn-beijing.volces.com/2125187037/071711135357575406.jpg?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKTP0VyX37NH37peqQWqz0vNsubkwJ5k6V4gXUG4l5jFNG%2F20260717%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260717T073202Z&X-Tos-Expires=43200&X-Tos-Security-Token=nChBSRDZTall6QTdZRVN1cm9C.CiQKEEZwNVZqRjExMmozQUV4aUQSEPG_JuzXIkWolaZzjqJml-YQnbbm0gYYzYbp0gYg-v3I6QcoBDCs7-stOh9Sb2xlRm9yQXJrQXNzZXQvUm9sZUZvckFya0Fzc2V0QgNhcmtSD1JvbGVGb3JBcmtBc3NldFgDegNhcms.qHN1GMAGoYrD8yo7xs02LAsqB7xLQHEpA8Pt1CyZlg1UkKeFaCh4eiwpUZl_Tbvg3BbVosV8Vyx7dhrT6Ep0hw&X-Tos-Signature=8111f50752a2ce3873288b20d2183ed13283853241953d94635c35354e3c7d7f&X-Tos-SignedHeaders=host",
"assetType": "Image",
"status": "ACTIVE"
}
]
}

3.12 创建真人认证H5会话

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/session

请求入参： 空

请求示例： 无

返回参数：

参数名称	参数类型	描述
h5Link	string	H5活体检测链接（用户复制到手机端完成认证）
bytedToken	string	认证Token（用于查询认证状态）
expiresIn	integer(int32)	Token有效期（秒）

返回示例：

JSON

{
"h5Link": "https://ark.volcengine.com/region:cn-beijing/mobile/livenees-face-manage/authorization?pl=W_IZrOw0_Ao8owvjo6_MC2rzuv74lVVQClrZnE7iLj6rNERC76ZzZKrnfSVweYDVQig4wOu3XkzTIBNveKDTVWY41WiVVB5ozekhgXG9ygHqZZkMGSrFjR3aw7m-iZugDv5O4kxqEgfpHEBdbVENesW8B6LXm-MAju2c68_-GRaMwaupUIMiXbIsZ1BiM_V5ASARxON2a15VnH2Pd7vgAdabFdLVWgKPWaC8Jj7jQCgT3t8MbO4oONyr7UeIb-PkbWxSy1McvfaNb4Z5HEZaEDNTLq-JrI5_aTY9Hfe3V_-X6cYVfUPKnK730soHEibRN6Te8yHob04LjhEY4xAFZtFt-0rUGFtXxiVgzaRwYm9ZWz0V70Cslk4v6NoC-3tggNKRucUwEnGPfkEFqyhPDeiR1-ZWB-u06Wh5XEPCdzCoqu5QkGi5WeNr44HBO0vWp3PtnqYcowBQ8FWISU0jYhReosVcTH5ysW9vXZAx-IkQtBMHaFlJ4dtB2Qf4OJQPfgEQcZ7cTksFX6cFG1E6L-EBHE40IOjt-D_Njvketu-wqgchY0a7CWmFsnBbmy0S6fB7K1evoQfFoJk7XU0z0TJrUcdprkOEDvpnO9osBmgYkhFoN9ZKBZbPqdF532-dksRMlLdr_Cm00a2HCbMS1FL9C8znUoXbJb3B2B3a5VQ2hAH_itZ_ylELCoxqqledWSJzk6KdqeI2H5A_lFM9FdB6QF8n2QeH9q9vMII-0MIbL-jmVeb632AnwA&uid=fa52e90c-d9fe-4bc8-ab6a-7e26a0e8a9c5",
"expiresIn": 120,
"bytedToken": "20260720142319F8E6E2D761C142D4E71D"
}

3.13 通过Token查询真人素材分组

接口地址：POST https://mjlm.coral-gpu.com:3000/v1/assets/asset-groups/by-byted-token

请求入参（JSON请求体）：

参数名	参数类型	是否必填	参数说明
getAssetGroupByBytedTokenBody	ConfirmVerificationRequestDTO	是
bytedToken	String	是	真人认证Token，由创建H5认证会话接口返回

请求示例：

JSON

{
"getAssetGroupByBytedTokenBody": {
"bytedToken": "20260720142319F8E6E2D761C142D4E71D"
}
}

返回参数：

参数名称	参数类型	描述
id	string	火山资产分组id

返回示例：

JSON

{
"id": "group-20260720142417-kg4jc"
}

4. 错误码及说明

4.1错误响应体

参数名	参数类型	是否必填	参数说明
error	obj	否	错误对象
code	string	是	机器识别细分错误码
message	string	是	人类可读错误描述
type	string	是	错误大类

请求示例：

JSON

{
"error": {
"code": "",
"message": "Invalid token (request id: 2026072303olkd1yzGoEl)",
"type": "new_api_error"
}
}

4.2错误类型

code	详细说明
new_api_error	转发平台错误
openai_error	OpenAI范式转发错误
upstream_error	上游渠道错误
volcengine_error	火山引擎（seedance）范式转发错误

4.3错误码

错误码	详细说明
invalid_token_key_request	令牌无效
invalid_request	无效请求，如post\get\put错误，url参数错误或Body体JSON格式错误。
distributor:no_available_channel	账户无有效可用渠道
count_token_failed	预估、本地计算token数异常
do_request_failed	请求上游渠道地址失败
gen_relay_info_failed	转发上游渠道业务失败
channel:invalid_key	上游渠道令牌无效
channel:response_time_exceeded	上游渠道响应超时
read_request_body_failed	请求上游渠道时，构建请求体异常，如请全体过大，读取上下文请求IO异常
read_response_body_failed	解释上游渠道响应报文异常
model_not_found	请求模型不存在，模型名称错误