# 素材管理

素材管理用于在视频生成等场景中引用图片/视频/音频素材。平台提供**两套**素材接口：

| 接口 | 路径 | 鉴权 | 适用 |
| --- | --- | --- | --- |
| 自有素材库 | `/api/business/v1/assets` | API Key 或 JWT | 当前未进入公开 OpenAPI，不作为独立接入入口 |
| 火山兼容素材 | `/api/ark/*` | 火山 V4 签名 | 火山引擎 SDK 迁移 |

> 自有素材库尚未收录到本次公开 OpenAPI，下方内容仅用于说明已有业务流程，不能作为只依据当前公开文档即可完成的独立接入示例。需要新接入时请先联系 SilvaMux 确认权限与契约。火山兼容素材接口可依据公开 `/api/ark` OpenAPI 契约接入。

本页内容：
- [自有素材库](#自有素材库)
- [火山兼容接口](#火山兼容接口)
- [在视频生成中引用素材](#在视频生成中引用素材)

## 自有素材库

基础路径 `/api/business/v1`，认证 `Authorization: Bearer sk_live_...` 或 JWT。

### 数据模型（AssetView）

```json
{
  "id": "AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y",
  "url": "https://example.com/image.png",
  "asset_type": "Image",
  "name": "cover-image",
  "asset_url": "asset://asset-123456",
  "status": "processing",
  "created_at": "2026-03-27T10:00:00Z"
}
```

| 字段 | 说明 |
| --- | --- |
| `id` | 素材 ID |
| `url` | 原始素材 URL |
| `asset_type` | 素材类型（`Image`/`Video`/`Audio`） |
| `name` | 素材名称 |
| `asset_url` | 素材引用地址，格式 `asset://<素材ID>`，用于视频生成引用 |
| `status` | `processing`、`active`、`failed`、`timeout`；仅 `active` 可用 |

### 端点

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `POST` | `/assets` | 创建素材（注册公网 URL） |
| `GET` | `/assets` | 列出素材（分页） |
| `GET` | `/assets/{asset_id}` | 获取单个素材 |

### 创建素材

```bash
curl -X POST https://www.silvamux.com/api/business/v1/assets \
  -H "Authorization: Bearer $SILVAMUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/image.png",
    "asset_type": "Image",
    "name": "cover-image"
  }'
```

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `url` | 是 | 素材的公开 URL |
| `asset_type` | 是 | `Image`、`Video`、`Audio` |
| `name` | 否 | 素材名称；省略时由素材 URL 推导 |

成功返回 `201`，响应体为 AssetView。新建后通常先 `processing`，后续变为 `active`、`failed` 或 `timeout`。后台每 5 秒轮询 `processing` 状态的素材，创建超过 24 小时仍未就绪的素材会被标记为 `timeout`。

### 列出素材

```bash
curl "https://www.silvamux.com/api/business/v1/assets?limit=20" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"
```

| 参数 | 说明 |
| --- | --- |
| `limit` | 每页数量，1-100，默认 20 |
| `cursor` | 分页游标，首次不传 |

### 获取单个素材

```bash
curl "https://www.silvamux.com/api/business/v1/assets/AST-01JQ8Y7P8R6L7S9T0U1V2W3X4Y" \
  -H "Authorization: Bearer $SILVAMUX_API_KEY"
```

常用于轮询素材状态，直到 `status` 变为 `active`。

### 最小调用流程

1. 准备一个外网可访问的素材 URL
2. `POST /assets` 创建，拿到 `id`、`asset_url`
3. 轮询 `GET /assets/{id}`，直到 `status` 变为 `active`
4. 用 `asset_url` 在视频生成中引用

> 引用非 `active` 状态的素材会返回 `InvalidParameter.asset_status` 错误。请确保素材状态为 `active` 后再在视频生成中引用。

## 火山兼容接口

兼容本页列出的火山引擎素材管理操作。**从火山引擎迁移的客户可以继续使用对应的火山引擎官方 SDK，将接入地址指向本平台，并将凭证换成平台签发的 AK/SK。**

| 项 | 值 |
| --- | --- |
| Endpoint | `https://www.silvamux.com/api/ark` |
| Region | `cn-beijing` |
| Service | `ark` |
| 鉴权 | 火山 V4 签名，使用平台签发的 AK/SK |
| 调用方式 | `POST /api/ark?Action=<Action>&Version=2024-01-01` |

### 接入准备

1. 控制台 → 凭据管理 → 创建 **Volcengine 兼容 (AK/SK)** 凭据，一次性返回 AK 与 SK（SK 仅此时可见）。
2. AK/SK 绑定组织，项目通过 `ProjectName` 字段指定。

### 配置 SDK

在火山引擎官方 SDK 对应的素材客户端中修改以下配置：

| 配置 | 值 |
| --- | --- |
| Endpoint | `https://www.silvamux.com/api/ark` |
| Region | `cn-beijing` |
| Access Key | 平台签发的 AK |
| Secret Key | 平台签发的 SK |

具体客户端类名和初始化方式以所使用的火山引擎 SDK 版本为准。本仓库不提供名为 `ArkAssetClient` 的独立客户端。

### 支持的操作

请求体字段名与火山引擎一致（驼峰、首字母大写）。

素材组（AssetGroup）：`CreateAssetGroup`（仅 AIGC，创建时回填组织级共享火山组 id）、`GetAssetGroup`、`ListAssetGroups`、`UpdateAssetGroup`、`DeleteAssetGroup`。`ListAssetGroups` 的 `Filter.GroupType` 可选，默认 `AIGC`（仅列 AIGC 组）；传 `LivenessFace` 列真人组，取其它值返回 `InvalidParameter.GroupType`。`DeleteAssetGroup` 对真人组同步删除上游真人火山组（`provider_group_id` 缺失直接报错），AIGC 组仅清本地（共享组不删）。

素材（Asset）：`CreateAsset`（`GroupId`+`URL`+`AssetType`+`Name`，可选 `GroupType`）`GetAsset`、`ListAssets`、`UpdateAsset`、`DeleteAsset`。`AssetType` 可选 `Image`/`Video`/`Audio`。

`CreateAsset` 的上游组按**目标组的类型**自动路由：指向 AIGC 组走普通 AIGC 素材入库（上传到组织级 AIGC 火山组）；指向 `CreateVisualValidateSession` + `GetVisualValidateResult` 流程返回的 LivenessFace 组即走真人素材入库，上游真人火山组 id 由平台内部解析，客户端无需知晓。完整流程见[人像认证（真人活体认证）](./liveness-verification.md)。

`ProjectName` 为空或填 `default` 用默认项目，填其它值按项目名精确匹配。

### 重要限制

- **历史素材不可见**：之前通过火山引擎控制台或其它账号上传的素材无法通过本接口访问，需重新上传。
- 素材类型区分：`CreateAsset` 指向 AIGC 组走普通 AIGC 素材（图片/视频/音频）；真人素材（LivenessFace）需先走 `CreateVisualValidateSession` + `GetVisualValidateResult` 完成活体校验，再把素材上传到返回的 LivenessFace 组，平台按组类型自动路由到真人上游组（见[人像认证（真人活体认证）](./liveness-verification.md)）。
- `CreateAsset` 需提供公网可访问的素材 URL，平台拉取入库。

### 错误码

| Code | 含义 |
| --- | --- |
| `InvalidSignature` | 签名校验失败（AK/SK 错、请求被篡改、时钟偏移过大） |
| `InvalidAction` | 不支持的 Action |
| `MissingParameter.*` | 缺少必填字段 |
| `InvalidParameter.*` | 字段值非法 |
| `NotFound.asset_id` / `NotFound.project` | 素材 / 项目不存在 |
| `SubscriptionRequired` | 组织未开通相应能力 |
| `InternalError` | 服务内部错误，记录 `RequestId` 联系支持 |

## 在视频生成中引用素材

素材 `active` 后，用 `asset_url`（`asset://...`）在视频生成的 `content` 中引用：

```json
{
  "model": "<MODEL_CALL_NAME>",
  "content": [
    {"type": "video_url", "video_url": "asset://asset-123456"},
    {"type": "text", "text": "让画面中的角色跳舞"}
  ]
}
```

### 迁移要点（火山引擎 → SilvaMux）

| 能力 | 火山引擎 | SilvaMux | 说明 |
| --- | --- | --- | --- |
| 对话（豆包） | `/api/v3/chat/completions` | `POST /api/v3/chat/completions` | 协议兼容，改 Base URL + Key，model 用平台调用名 |
| 视频生成 | `/contents/generations/tasks` | `POST /api/v3/contents/generations/tasks` | **自有接口 + API Key**，不走 V4 签名 |
| 素材管理 | 火山官方接口 | `POST /api/ark/*`（本页）或 `/api/business/v1/assets` | 两套可选 |

- 视频生成走 API Key，不走 V4 签名。V4 签名仅用于本页素材接口。
- API Key（`sk_live_`）与 AK/SK 在控制台分别创建，不同。
- `model` 使用模型广场或模型列表展示的真实调用名，不是火山 endpoint ID。
- 视频与 3D 任务支持任务列表、单任务查询和创建时传入 `callback_url`；字段与鉴权以公开 OpenAPI 契约为准。