# 上传素材

> 用虚拟密钥直接上传图片、视频、音频到企业火山素材库，查询审核状态、列出和删除素材。

Base URL：`https://platform.sgt.site`

本页接口用于管理企业火山素材库中的素材。创建后查询审核状态，素材可用后再用于生成；鉴权与文件输入方式见[文件与素材约定](business-auth.md)；与 `/media/v1/files` 的区别见[参考文件与素材：选择上传接口](media-files.md#media-files-h-cf1470ee)。

| 方法 | 路径 |
| --- | --- |
| POST | `/api/volcengine/assets/create` |
| POST | `/api/volcengine/assets/check` |
| POST | `/api/volcengine/assets/list` |
| POST | `/api/volcengine/assets/delete` |

<a id="business-assets-section-1"></a>

## 创建素材

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `file` / `base64` / `url` | — | 文件内容，三选一，见[文件输入](business-auth.md#business-auth-section-2) |
| `content_type` | string | 仅配合纯 Base64 使用，声明 MIME |
| `asset_type` | string | `Image`、`Video`、`Audio`（不区分大小写）。文件和 Base64 可省略，按内容识别；填写时须与实际类型一致。**用 URL 上传视频或音频时必须填写**，否则按 Image 处理 |
| `name` | string | 素材名称，1–64 个字符；省略时自动生成 |
| `group_id` | string | 本企业已有的素材组 ID；省略时使用企业默认素材组（首次自动创建） |
| `wait_seconds` | integer | 创建后等待审核结果的秒数，0–30，默认 30；不含上传耗时 |

表单上传时，`name`、`group_id`、`asset_type`、`wait_seconds` 作为普通文本字段提交。

Base64 上传图片：

```http
POST /api/volcengine/assets/create HTTP/1.1
Host: platform.sgt.site
Authorization: Bearer YOUR_VIRTUAL_KEY
Content-Type: application/json
```

```json
{
  "base64": "data:image/png;base64,BASE64_IMAGE_DATA",
  "name": "人物正面照",
  "wait_seconds": 30
}
```

表单上传视频：

```bash
curl -X POST "$GATEWAY_ORIGIN/api/volcengine/assets/create" \
  -H "Authorization: Bearer $KEY" \
  -F "file=@./motion.mp4;type=video/mp4" \
  -F "name=人物动作参考" \
  -F "wait_seconds=10"
```

公网 URL 上传音频：

```json
{
  "url": "https://media.example.com/voice.mp3",
  "asset_type": "Audio",
  "name": "旁白音频"
}
```

- 文件和 Base64 由平台存入企业的私有 TOS 桶，再提交火山入库；公网 URL 由火山直接下载，平台不转存，地址须能被公网访问。
- 素材库满额时，平台只在火山明确返回“容量已满”后，删除本企业最早创建且未被使用的一条素材并重试一次；不会删除其他企业的素材或正在使用的素材。
- 同一企业的写操作（创建、删除）依次执行，前一个未完成时返回 409。

响应（仍在处理）：

```json
{
  "success": true,
  "data": {
    "id": "asset-example",
    "uri": "asset://asset-example",
    "status": "Processing"
  }
}
```

响应（审核通过）：

```json
{
  "success": true,
  "data": {
    "id": "asset-example",
    "uri": "asset://asset-example",
    "status": "Active",
    "name": "人物正面照",
    "asset_type": "Image",
    "group_id": "group-example",
    "url": "https://..."
  }
}
```

响应（审核未通过，HTTP 仍为 200）：

```json
{
  "success": true,
  "data": {
    "id": "asset-example",
    "uri": "asset://asset-example",
    "status": "Failed",
    "error_code": "ERROR_CODE_FROM_VOLCENGINE",
    "error_message": "审核未通过的原因"
  }
}
```

| 字段 | 说明 |
| --- | --- |
| `id` | 素材 ID，创建成功即返回，请立即保存 |
| `uri` | 素材引用标识 `asset://<id>`，状态为 `Active` 后才能使用 |
| `status` | `Processing`（处理或审核中）、`Active`（可用）、`Failed`（未通过） |
| `name` / `asset_type` / `group_id` | 素材名称、类型、所属素材组 |
| `url` | 火山返回的预览地址，会过期，不能当作永久地址 |
| `error_code` / `error_message` | `Failed` 时的原因 |
| `check_pending` | 为 `true` 表示素材已创建，但等待期间查询状态失败；请用[查询素材](business-assets.md#business-assets-section-2)继续查询，**不要重新创建** |

**创建成功不等于可用。**`wait_seconds` 内得到 `Active` 或 `Failed` 会立即返回；超时仍为 `Processing` 时，稍后调用[查询素材](business-assets.md#business-assets-section-2)。审核未通过同样是 HTTP 200 且 `success: true`，必须检查 `data.status`。

<a id="business-assets-section-2"></a>

## 查询素材

```json
{"id": "asset-example"}
```

返回字段与[创建素材](business-assets.md#business-assets-section-1)相同。只能查询本企业通过平台创建的素材；建议每隔几秒查询一次，直到 `status` 不再是 `Processing`。

<a id="business-assets-section-3"></a>

## 素材列表

```json
{"page": 1, "page_size": 20, "group_id": "group-example"}
```

| 字段 | 说明 |
| --- | --- |
| `page` | 页码，从 1 开始，默认 1 |
| `page_size` | 每页条数，1–100，默认 20 |
| `group_id` | 可选，只列出指定素材组 |

所有字段都可省略，但请求体须为 JSON 对象（至少传 `{}`）。

```json
{
  "success": true,
  "data": {
    "items": [
      {"id": "asset-example", "uri": "asset://asset-example", "status": "Active", "name": "人物正面照", "asset_type": "Image", "group_id": "group-example"}
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

列表只包含本企业通过平台创建的素材，火山控制台中已有的素材不会出现。并发创建或删除时，翻页结果可能重复或遗漏。

<a id="business-assets-section-4"></a>

## 删除素材

```json
{"id": "asset-example"}
```

```json
{"success": true, "data": {"id": "asset-example", "deleted": true}}
```

只能删除本企业通过平台创建的素材。删除后素材不能再用于生成，请先确认没有进行中的任务在使用它。