# 文件与素材约定

> 平台 API 中文件和素材操作的输入方式、类型与大小限制、响应格式和错误处理。

文件与素材操作沿用平台统一的[地址与鉴权](access.md)，使用 JSON 或表单上传。**上传素材**把文件加入企业绑定的火山 AIGC 素材库，返回素材 ID 和审核状态；**上传文件**只把文件存到平台存储，返回 7 天内有效的下载地址。两类接口都不消耗模型额度。

本页说明 `/api/files/upload` 和 `/api/volcengine/assets/*` 的约定，响应使用 `success/data` 包装。平台同时提供 `/media/v1/files`，返回统一的 `media.file` 对象，供媒体生成按 `file_id` 或 `asset_id` 引用。三组接口怎么选，见[参考文件与素材：选择上传接口](media-files.md#media-files-h-cf1470ee)。

Base URL 为当前网关根地址 `https://platform.sgt.site`。将下面的完整接口路径直接加在根地址后，不额外添加 `/v1` 或 `/media/v1`。

| 方法与相对路径 | 用途 |
| --- | --- |
| `POST /api/volcengine/assets/create` | 上传素材，返回素材 ID 与审核状态 |
| `POST /api/volcengine/assets/check` | 查询素材处理与审核结果 |
| `POST /api/volcengine/assets/list` | 分页列出本企业素材 |
| `POST /api/volcengine/assets/delete` | 删除本企业素材 |
| `POST /api/files/upload` | 上传文件，返回 7 天有效地址 |

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

## 鉴权

使用[地址与鉴权](access.md)中的完整虚拟密钥，不需要另外签发素材凭证。除通用的 `Authorization: Bearer YOUR_VIRTUAL_KEY` 外，这组接口还接受下面的写法；两种任选其一，不能同时发送：

```http
X-API-Key: YOUR_VIRTUAL_KEY
```

- 不接受火山 V4 签名（`HMAC-SHA256` 开头的 `Authorization`），也不使用火山 AK/SK。
- 地址不能带查询参数，请求体不能压缩（不能带 `Content-Encoding`）。
- 平台实时检查密钥状态、有效期、IP 白名单以及所属企业和组织状态；模型余额为零不影响这些接口。

**使用前提：**企业已由平台管理员绑定启用了素材能力的火山渠道。以文件或 Base64 上传素材、以及上传文件接口，还要求该渠道配置了私有 TOS 存储桶。渠道、火山账号和项目都由企业绑定决定，请求中不能指定。本企业正常状态的成员和应用共享同一批素材。

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

## 文件输入

上传素材和上传文件共用以下三种输入方式，每次只能用一种：

| 方式 | 写法 |
| --- | --- |
| 表单 | `Content-Type: multipart/form-data`，文件字段名为 `file`，只能有一个文件；其他文本字段每个不超过 1024 字节，同名字段不能重复，未列出的字段返回 400 |
| Base64 | JSON 字段 `base64`，可填完整 Data URI（`data:video/mp4;base64,...`）或纯 Base64；纯 Base64 可用 `content_type` 声明 MIME，省略时按内容识别 |
| URL | JSON 字段 `url`，填公网 HTTP(S) 地址；也兼容在 `url` 里填完整 Data URI |

JSON 请求必须带 `Content-Type: application/json`，`url` 与 `base64` 必须且只能填一个，出现未列出的字段返回 400。

支持的文件类型与大小：

| 类型 | 格式 / MIME | 大小上限 |
| --- | --- | --- |
| Image | PNG `image/png`、JPEG `image/jpeg`、WebP `image/webp` | 10 MiB，且不超过 1600 万像素 |
| Video | MP4 `video/mp4`、MOV `video/quicktime` | 200 MiB |
| Audio | WAV `audio/wav`、MP3 `audio/mpeg` | 15 MiB |

- 平台检查文件大小和实际内容类型，声明的 MIME 与实际内容不一致会返回 400；图片会完整解码校验。
- 视频、音频的编码、时长、画幅由火山入库流程判断；上传文件成功不代表满足某个模型的生成要求，生成前请对照各模型的官方输入限制。
- Base64 会让体积增加约三分之一，大文件优先用表单或 URL。

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

## 响应格式

成功返回 HTTP 200：

```json
{"success": true, "data": {}}
```

失败返回非 2xx 状态码：

```json
{
  "success": false,
  "error": {"code": "GatewayInvalidParameter", "message": "Invalid asset request"},
  "request_id": "request_example"
}
```

| HTTP | error.code | 常见原因 |
| --- | --- | --- |
| 400 | `GatewayInvalidParameter` | 字段不合法、文件类型或大小不符、同时传了多种输入、地址带查询参数 |
| 403 | `GatewayAccessDenied` | 虚拟密钥无效、已过期或被撤销，使用了 V4 签名，或访问了非本企业的素材 |
| 409 | `GatewayOperationConflict` | 本企业有未完成或结果待确认的素材写操作 |
| 422 | `GatewayScanLimitExceeded` | 素材列表范围过大，请指定 `group_id` |
| 502 | `GatewayTOSUploadFailed` | 文件存入 TOS 失败，素材未提交；请联系管理员检查存储桶配置 |
| 502 | `GatewayUpstreamUnavailable` | 火山处理结果未知，不要自动重试写操作 |
| 503 | `GatewayNotConfigured` | 企业未绑定渠道、渠道未启用素材能力或未配置 TOS |
| 500 | `GatewayInternalError` | 其他内部错误 |

火山拒绝请求时（例如参数校验不通过、素材库满额且无法自动清理），`error.code` 和 `error.message` 为火山返回的错误码与说明，`request_id` 为火山的 RequestId；HTTP 状态沿用火山返回的 4xx（火山返回 2xx 但带错误时为 400），火山服务异常时为 502。