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

本文介绍通过 ModelVerse API 管理火山方舟私域虚拟人像素材的完整流程，包括素材组管理和素材资产管理。
[官方文档](https://www.volcengine.com/docs/82379/2333601?lang=zh)。

## 服务地址

| 接口类型 | 方法 | 地址 |
| --- | --- | --- |
| 创建素材组 | 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 <your-api-key>`

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

```bash
export ENDPOINT="https://api.modelverse.cn"
export MODELVERSE_API_KEY="<your-api-key>"
```

## 使用流程

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

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

## 素材组管理

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

### 创建素材组

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

**POST** `/v1/volce-asset/groups/create`

#### 请求体

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

#### 参数说明

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

#### 请求示例

```bash
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"
  }'
```

#### 响应示例

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

#### 响应字段

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

### 查询素材组列表

**POST** `/v1/volce-asset/groups/list`

#### 请求体

```json
{
  "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。 |

#### 请求示例

```bash
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
  }'
```

#### 响应示例

```json
{
  "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`

#### 请求体

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

#### 请求示例

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

#### 响应示例

```json
{
  "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`

#### 请求体

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

#### 参数说明

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

#### 请求示例

```bash
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": "用于数字人生成"
  }'
```

#### 响应示例

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

### 删除素材组

删除指定素材组。

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

**POST** `/v1/volce-asset/groups/delete`

#### 请求体

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

#### 请求示例

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

#### 响应示例

```json
{}
```

## 素材资产管理

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

### 创建素材

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

**POST** `/v1/volce-asset/assets/create`

#### 请求体

```json
{
  "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。 |

#### 请求示例

```bash
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"
  }'
```

#### 响应示例

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

### 查询素材列表

**POST** `/v1/volce-asset/assets/list`

#### 请求体

```json
{
  "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`。 |

#### 请求示例

```bash
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
  }'
```

#### 响应示例

```json
{
  "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`

#### 请求体

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

#### 请求示例

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

#### 响应示例

```json
{
  "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`

#### 请求体

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

#### 请求示例

```bash
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"
  }'
```

#### 响应示例

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

### 删除素材

删除指定素材资产。

**POST** `/v1/volce-asset/assets/delete`

#### 请求体

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

#### 请求示例

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

#### 响应示例

```json
{}
```

## 注意事项

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