Skip to Content
模型 API 文档按量API调用指南视频生成火山方舟素材管理

火山方舟素材管理

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

服务地址

接口类型方法地址
创建真人认证会话GET/v1/volce-asset/visual-validate/sessions
查询真人认证结果POST/v1/volce-asset/visual-validate/result
查询素材组列表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>"

使用流程

真人素材通常按以下流程使用：

  1. 调用 GET /v1/volce-asset/visual-validate/sessions 创建真人认证会话，获取 h5_link 和 bearer_token。
  2. 在浏览器中打开 h5_link，按页面提示完成真人认证。
  3. 调用 POST /v1/volce-asset/visual-validate/result 查询认证状态。状态为 group_ready 时会返回 group_id。
  4. 使用 group_id 调用素材创建接口，将图片、视频或音频 URL 添加到该素材组。
  5. 通过素材查询接口确认素材状态为 Active 后，在支持私域素材的模型调用中使用对应素材。

真人认证

创建真人认证会话

创建一次真人认证会话。接口返回的 h5_link 需要由真实用户在浏览器中打开并完成认证。

GET /v1/volce-asset/visual-validate/sessions

请求示例

curl --location "$ENDPOINT/v1/volce-asset/visual-validate/sessions" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY"

响应示例

{
 "bearer_token": "2b7b3f8e-0f7d-4d4c-8f0f-xxxxxxxxxxxx",
 "h5_link": "https://example.com/visual-validate?token=xxxx"
}

响应字段

字段类型说明
bearer_tokenstring本次认证会话的查询凭证，用于后续查询认证结果。有效期约 30 分钟。
h5_linkstring真人认证 H5 链接。业务方需要引导用户打开该链接完成认证。

查询真人认证结果

认证完成后，使用 bearer_token 查询认证状态和素材组 ID。

POST /v1/volce-asset/visual-validate/result

请求体

{
 "bearer_token": "2b7b3f8e-0f7d-4d4c-8f0f-xxxxxxxxxxxx"
}

参数说明

字段类型是否必须说明
bearer_tokenstring是创建认证会话时返回的查询凭证。

请求示例

curl --location "$ENDPOINT/v1/volce-asset/visual-validate/result" \
 --header "Authorization: Bearer $MODELVERSE_API_KEY" \
 --header "Content-Type: application/json" \
 --data '{
 "bearer_token": "2b7b3f8e-0f7d-4d4c-8f0f-xxxxxxxxxxxx"
 }'

响应示例

{
 "status": "group_ready",
 "group_id": "group-20260331145705-xxxxx"
}

响应字段

字段类型说明
statusstring认证会话状态。
group_idstring真人认证通过后创建的素材组 ID。仅在素材组已就绪时返回有效值。

status 枚举

值含义
created会话已创建，用户尚未完成真人认证或回调尚未完成处理。
group_ready真人认证通过，素材组已创建，可以继续创建素材。
failed真人认证失败。
expired会话已过期。

素材组管理

素材组用于归类和管理素材。真人认证通过后会自动创建一个 LivenessFace 类型素材组。

查询素材组列表

POST /v1/volce-asset/groups/list

请求体

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

参数说明

字段类型是否必须说明
filter.group_idsstring[]否素材组 ID 列表。为空时查询当前账号可见的全部素材组。
filter.group_typestring否素材组类型。可选值：LivenessFace、AIGC。
filter.namestring否素材组名称，支持模糊匹配。
page_numberinteger否页码，从 1 开始，默认 1。
page_sizeinteger否每页数量，默认 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": "LivenessFace"
 },
 "page_number": 1,
 "page_size": 10
 }'

响应示例

{
 "items": [
 {
 "id": "group-20260331145705-xxxxx",
 "name": "真人素材组",
 "description": "用于数字人生成",
 "group_type": "LivenessFace",
 "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
}

响应字段

字段类型说明
itemsobject[]素材组列表。
items[].idstring素材组 ID。
items[].namestring素材组名称。
items[].descriptionstring素材组描述。
items[].group_typestring素材组类型。
items[].project_namestring资源所属项目。
items[].create_timestring创建时间。
items[].update_timestring更新时间。
total_countinteger满足条件的素材组总数。
page_numberinteger当前页码。
page_sizeinteger每页数量。

查询素材组详情

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": "LivenessFace",
 "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"
}

参数说明

字段类型是否必须说明
idstring是素材组 ID。
namestring否新素材组名称，name 和 description 至少传一个。
descriptionstring否新素材组描述，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_idstring是素材所属素材组 ID。
urlstring是素材公网可访问 URL。
namestring否素材名称。
asset_typestring是素材类型。可选值：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": "LivenessFace",
 "statuses": ["Active"],
 "name": "test"
 },
 "page_number": 1,
 "page_size": 10,
 "sort_by": "CreateTime",
 "sort_order": "Desc"
}

参数说明

字段类型是否必须说明
filter.group_idsstring[]否素材组 ID 列表。为空时查询当前账号可见素材组下的素材。
filter.group_typestring否素材组类型。可选值：LivenessFace、AIGC；默认 LivenessFace。
filter.statusesstring[]否素材状态列表。可选值：Active、Processing、Failed。
filter.namestring否素材名称，支持模糊匹配。
page_numberinteger否页码，从 1 开始，默认 1。
page_sizeinteger否每页数量，默认 10，最大 100。
sort_bystring否排序字段。可选值：CreateTime、UpdateTime、GroupId。
sort_orderstring否排序方向。可选值：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"],
 "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
}

响应字段

字段类型说明
itemsobject[]素材列表。
items[].idstring素材资产 ID。
items[].namestring素材名称。
items[].urlstring素材访问地址。
items[].group_idstring素材所属素材组 ID。
items[].asset_typestring素材类型：Image、Video、Audio。
items[].statusstring素材状态：Active、Processing、Failed。
items[].error.codestring处理失败时的错误码。
items[].error.messagestring处理失败时的错误信息。
items[].project_namestring资源所属项目。
items[].create_timestring创建时间。
items[].update_timestring更新时间。
total_countinteger满足条件的素材总数。
page_numberinteger当前页码。
page_sizeinteger每页数量。

查询素材详情

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 所属账号做权限校验。只能查询和管理当前账号可见的素材组和素材。
  • 创建素材时，url 必须是服务端可访问的公网 URL。
  • 素材创建是异步处理，assets/create 返回素材 ID 后，请轮询 assets/get 或 assets/list，等待 status 变为 Active。
  • 删除素材组会级联删除组内全部素材，操作不可逆。
  • 接口错误码请参考「错误码」文档。
Last updated on
doubao-seedance-2-0火山方舟私域虚拟人像素材管理