火山方舟私域虚拟人像素材管理

本文介绍通过 ModelVerse API 管理火山方舟私域虚拟人像素材的完整流程，包括素材组管理和素材资产管理。

服务地址

接口类型	方法	地址
创建素材组	POST	`/v1/volce-asset/groups/create`
查询素材组列表	POST	`/v1/volce-asset/groups/list`
查询素材组详情	POST	`/v1/volce-asset/groups/get`
更新素材组	POST	`/v1/volce-asset/groups/update`
删除素材组	POST	`/v1/volce-asset/groups/delete`
创建素材	POST	`/v1/volce-asset/assets/create`
查询素材列表	POST	`/v1/volce-asset/assets/list`
查询素材详情	POST	`/v1/volce-asset/assets/get`
更新素材	POST	`/v1/volce-asset/assets/update`
删除素材	POST	`/v1/volce-asset/assets/delete`

认证方式：Authorization: Bearer <API_KEY>

请求示例中使用中国大陆节点：


export ENDPOINT="https://api.modelverse.cn"
export MODELVERSE_API_KEY="<YOUR_API_KEY>"

使用流程

虚拟人像素材通常按以下流程使用：

调用 POST /v1/volce-asset/groups/create 创建素材组，并将 group_type 设置为 AIGC。
使用返回的素材组 ID 作为 group_id 调用素材创建接口，将图片、视频或音频 URL 添加到该素材组。
通过素材查询接口确认素材状态为 Active 后，在支持私域素材的模型调用中使用对应素材。

素材组管理

素材组用于归类和管理素材。虚拟人像素材组需要通过接口创建，创建时 group_type 必须设置为 AIGC。

创建素材组

创建虚拟人像素材组。调用成功后，使用返回的素材组 ID 创建素材。

POST /v1/volce-asset/groups/create

请求体


{
 "name": "虚拟人像素材组",
 "description": "用于数字人生成",
 "group_type": "AIGC"
}

参数说明

字段	类型	是否必须	说明
name	string	是	素材组名称。
description	string	否	素材组描述。
group_type	string	是	素材组类型。虚拟人像素材必须传 `AIGC`。

请求示例


curl --location "$ENDPOINT/v1/volce-asset/groups/create" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "name": "虚拟人像素材组",
 "description": "用于数字人生成",
 "group_type": "AIGC"
 }'

响应示例


{
 "id": "group-20260331145705-xxxxx"
}

响应字段

字段	类型	说明
id	string	素材组 ID。

查询素材组列表

POST /v1/volce-asset/groups/list

请求体


{
 "filter": {
 "group_ids": ["group-20260331145705-xxxxx"],
 "group_type": "AIGC",
 "name": "test"
 },
 "page_number": 1,
 "page_size": 10
}

参数说明

字段	类型	是否必须	说明
filter.group_ids	string[]	否	素材组 ID 列表。为空时查询当前账号可见的全部素材组。
filter.group_type	string	否	素材组类型。可选值：`LivenessFace`、`AIGC`。虚拟人像素材使用 `AIGC`。
filter.name	string	否	素材组名称，支持模糊匹配。
page_number	integer	否	页码，从 1 开始，默认 1。
page_size	integer	否	每页数量，默认 10，最大 100。

请求示例


curl --location "$ENDPOINT/v1/volce-asset/groups/list" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "filter": {
 "group_type": "AIGC"
 },
 "page_number": 1,
 "page_size": 10
 }'

响应示例


{
 "items": [
 {
 "id": "group-20260331145705-xxxxx",
 "name": "虚拟人像素材组",
 "description": "用于数字人生成",
 "group_type": "AIGC",
 "project_name": "default",
 "create_time": "2026-03-31T06:57:05Z",
 "update_time": "2026-03-31T06:57:05Z"
 }
 ],
 "total_count": 1,
 "page_number": 1,
 "page_size": 10
}

响应字段

字段	类型	说明
items	object[]	素材组列表。
items[].id	string	素材组 ID。
items[].name	string	素材组名称。
items[].description	string	素材组描述。
items[].group_type	string	素材组类型。
items[].project_name	string	资源所属项目。
items[].create_time	string	创建时间。
items[].update_time	string	更新时间。
total_count	integer	满足条件的素材组总数。
page_number	integer	当前页码。
page_size	integer	每页数量。

查询素材组详情

POST /v1/volce-asset/groups/get

请求体


{
 "id": "group-20260331145705-xxxxx"
}

请求示例


curl --location "$ENDPOINT/v1/volce-asset/groups/get" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "group-20260331145705-xxxxx"
 }'

响应示例


{
 "id": "group-20260331145705-xxxxx",
 "name": "虚拟人像素材组",
 "description": "用于数字人生成",
 "group_type": "AIGC",
 "project_name": "default",
 "create_time": "2026-03-31T06:57:05Z",
 "update_time": "2026-03-31T06:57:05Z"
}

更新素材组

更新素材组名称或描述。

POST /v1/volce-asset/groups/update

请求体


{
 "id": "group-20260331145705-xxxxx",
 "name": "new-name",
 "description": "new-description"
}

参数说明

字段	类型	是否必须	说明
id	string	是	素材组 ID。
name	string	否	新素材组名称，`name` 和 `description` 至少传一个。
description	string	否	新素材组描述，`name` 和 `description` 至少传一个。

请求示例


curl --location "$ENDPOINT/v1/volce-asset/groups/update" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "group-20260331145705-xxxxx",
 "name": "虚拟人像素材组",
 "description": "用于数字人生成"
 }'

响应示例


{
 "id": "group-20260331145705-xxxxx"
}

删除素材组

删除指定素材组。

风险提示：删除素材组会级联删除组内全部素材，操作不可逆。删除前请确认该素材组和组内素材不再被业务使用。

POST /v1/volce-asset/groups/delete

请求体


{
 "id": "group-20260331145705-xxxxx"
}

请求示例


curl --location "$ENDPOINT/v1/volce-asset/groups/delete" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "group-20260331145705-xxxxx"
 }'

响应示例

{}

素材资产管理

素材资产表示素材组中的单个素材。创建素材时需要提供公网可访问 URL，当前不支持 Base64 上传。

创建素材

在指定素材组中创建素材。调用成功只表示素材已提交，素材仍会经过异步处理。请通过查询素材详情或素材列表确认 status 为 Active 后再使用。

POST /v1/volce-asset/assets/create

请求体


{
 "group_id": "group-20260331145705-xxxxx",
 "url": "https://example.com/image.jpg",
 "name": "test-image",
 "asset_type": "Image"
}

参数说明

字段	类型	是否必须	说明
group_id	string	是	素材所属素材组 ID。
url	string	是	素材公网可访问 URL。
name	string	否	素材名称。
asset_type	string	是	素材类型。可选值：`Image`、`Video`、`Audio`。

素材限制

类型	主要限制
`Image`	支持 `jpeg/png/webp/bmp/tiff/gif/heic/heif`；宽高比 `(0.4, 2.5)`；宽高长度 `(300, 6000)` px；单图小于 30 MB。
`Video`	支持 `mp4/mov`；分辨率 `480p/720p/1080p`；时长 `[2, 15]` 秒；宽高比 `[0.4, 2.5]`；宽高 `[300, 6000]` px；总像素数 `[409600, 2086876]`；小于 50 MB；FPS `[24, 60]`。
`Audio`	支持 `wav/mp3`；时长 `[2, 15]` 秒；小于 15 MB。

请求示例


curl --location "$ENDPOINT/v1/volce-asset/assets/create" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "group_id": "group-20260331145705-xxxxx",
 "url": "https://example.com/image.jpg",
 "name": "test-image",
 "asset_type": "Image"
 }'

响应示例


{
 "id": "Asset-20260331150000-xxxxx"
}

查询素材列表

POST /v1/volce-asset/assets/list

请求体


{
 "filter": {
 "group_ids": ["group-20260331145705-xxxxx"],
 "group_type": "AIGC",
 "statuses": ["Active"],
 "name": "test"
 },
 "page_number": 1,
 "page_size": 10,
 "sort_by": "CreateTime",
 "sort_order": "Desc"
}

参数说明

字段	类型	是否必须	说明
filter.group_ids	string[]	否	素材组 ID 列表。为空时查询当前账号可见素材组下的素材。
filter.group_type	string	否	素材组类型。可选值：`LivenessFace`、`AIGC`；虚拟人像素材使用 `AIGC`。
filter.statuses	string[]	否	素材状态列表。可选值：`Active`、`Processing`、`Failed`。
filter.name	string	否	素材名称，支持模糊匹配。
page_number	integer	否	页码，从 1 开始，默认 1。
page_size	integer	否	每页数量，默认 10，最大 100。
sort_by	string	否	排序字段。可选值：`CreateTime`、`UpdateTime`、`GroupId`。
sort_order	string	否	排序方向。可选值：`Desc`、`Asc`。

请求示例


curl --location "$ENDPOINT/v1/volce-asset/assets/list" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "filter": {
 "group_ids": ["group-20260331145705-xxxxx"],
 "group_type": "AIGC",
 "statuses": ["Active"]
 },
 "page_number": 1,
 "page_size": 10
 }'

响应示例


{
 "items": [
 {
 "id": "Asset-20260331150000-xxxxx",
 "name": "test-image",
 "url": "https://example.com/asset-url",
 "group_id": "group-20260331145705-xxxxx",
 "asset_type": "Image",
 "status": "Active",
 "error": {
 "code": "",
 "message": ""
 },
 "project_name": "default",
 "create_time": "2026-03-31T07:00:00Z",
 "update_time": "2026-03-31T07:00:30Z"
 }
 ],
 "total_count": 1,
 "page_number": 1,
 "page_size": 10
}

响应字段

字段	类型	说明
items	object[]	素材列表。
items[].id	string	素材资产 ID。
items[].name	string	素材名称。
items[].url	string	素材访问地址。
items[].group_id	string	素材所属素材组 ID。
items[].asset_type	string	素材类型：`Image`、`Video`、`Audio`。
items[].status	string	素材状态：`Active`、`Processing`、`Failed`。
items[].error.code	string	处理失败时的错误码。
items[].error.message	string	处理失败时的错误信息。
items[].project_name	string	资源所属项目。
items[].create_time	string	创建时间。
items[].update_time	string	更新时间。
total_count	integer	满足条件的素材总数。
page_number	integer	当前页码。
page_size	integer	每页数量。

查询素材详情

POST /v1/volce-asset/assets/get

请求体


{
 "id": "Asset-20260331150000-xxxxx"
}

请求示例


curl --location "$ENDPOINT/v1/volce-asset/assets/get" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "Asset-20260331150000-xxxxx"
 }'

响应示例


{
 "id": "Asset-20260331150000-xxxxx",
 "name": "test-image",
 "url": "https://example.com/asset-url",
 "group_id": "group-20260331145705-xxxxx",
 "asset_type": "Image",
 "status": "Active",
 "error": {
 "code": "",
 "message": ""
 },
 "project_name": "default",
 "create_time": "2026-03-31T07:00:00Z",
 "update_time": "2026-03-31T07:00:30Z"
}

更新素材

当前仅支持更新素材名称。

POST /v1/volce-asset/assets/update

请求体


{
 "id": "Asset-20260331150000-xxxxx",
 "name": "new-name"
}

请求示例


curl --location "$ENDPOINT/v1/volce-asset/assets/update" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "Asset-20260331150000-xxxxx",
 "name": "new-name"
 }'

响应示例


{
 "id": "Asset-20260331150000-xxxxx"
}

删除素材

删除指定素材资产。

POST /v1/volce-asset/assets/delete

请求体


{
 "id": "Asset-20260331150000-xxxxx"
}

请求示例


curl --location "$ENDPOINT/v1/volce-asset/assets/delete" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "id": "Asset-20260331150000-xxxxx"
 }'

响应示例

{}

注意事项

所有接口都会按当前 API Key 所属账号做权限校验。只能查询和管理当前账号可见的素材组和素材。
虚拟人像素材组需要通过 groups/create 接口创建，group_type 必须使用 AIGC。
创建素材时，url 必须是服务端可访问的公网 URL。
素材创建是异步处理，assets/create 返回素材 ID 后，请轮询 assets/get 或 assets/list，等待 status 变为 Active。
删除素材组会级联删除组内全部素材，操作不可逆。
接口错误码请参考「错误码」文档。