# 火山方舟素材管理

本文介绍通过 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 <your-api-key>`

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

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

#### 请求示例

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

#### 响应示例

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

#### 响应字段

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

### 查询真人认证结果

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

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

#### 请求体

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

#### 参数说明

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

#### 请求示例

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

#### 响应示例

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

#### 响应字段

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

#### status 枚举

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

## 素材组管理

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

### 查询素材组列表

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

#### 请求体

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

#### 参数说明

| 字段 | 类型 | 是否必须 | 说明 |
| --- | --- | --- | --- |
| `filter.group_ids` | string[] | 否 | 素材组 ID 列表。为空时查询当前账号可见的全部素材组。 |
| `filter.group_type` | string | 否 | 素材组类型。可选值：`LivenessFace`、`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": "LivenessFace"
    },
    "page_number": 1,
    "page_size": 10
  }'
```

#### 响应示例

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

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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": "LivenessFace",
  "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": "LivenessFace",
    "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`；默认 `LivenessFace`。 |
| `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"],
      "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 所属账号做权限校验。只能查询和管理当前账号可见的素材组和素材。
- 创建素材时，`url` 必须是服务端可访问的公网 URL。
- 素材创建是异步处理，`assets/create` 返回素材 ID 后，请轮询 `assets/get` 或 `assets/list`，等待 `status` 变为 `Active`。
- 删除素材组会级联删除组内全部素材，操作不可逆。
- 接口错误码请参考 [错误码](/docs/modelverse/api_doc/common/error-code.md)。