# 参考文件与素材

> 在同一企业内管理临时参考文件与需审核的厂商素材，用文件 ID 或素材 ID 参与生成。

<a id="media-files-h-cf1470ee"></a>

## 选择上传接口

平台 API 有三组上传接口，按用途选择：

| 接口 | 什么时候用 | 拿到什么、怎么用 |
| --- | --- | --- |
| `POST /media/v1/files`，purpose 为 reference | 媒体生成要引用参考图、首帧、尾帧、参考视频或音频，且模型不要求素材库 | 文件 `id`，填进生成请求的 `references[].file_id`；7 天有效，无需审核。本页 |
| `POST /media/v1/files`，purpose 为 provider_asset | 模型的 `requires_asset` 为 `true`，或想长期复用审核过的素材 | 素材 `asset_id`，审核通过后填进 `references[].asset_id`。本页 |
| `POST /api/files/upload` | 只需要一个模型或第三方能直接读取的临时 URL，例如填进 `references[].url` | `data.file_url`，7 天有效。见[上传文件](business-files.md) |
| `/api/volcengine/assets/*` | 用 `success/data` 格式管理企业火山素材库：创建、查审核状态、列表、删除 | 素材 `data.id` 与审核状态。见[上传素材](business-assets.md) |

不需要参考素材时可以跳过上传，直接提交生成。生成请求中的每项参考只能选 `url`、`file_id`、`asset_id` 其中一种来源，文件 `id` 和 `asset_id` 不能互换。上传成功不代表模型一定接受该文件，提交前对照模型的 `references` 约束，见[模型列表：媒体模型返回字段](models.md#models-media-fields)。

<a id="media-files-h-d2f609c1"></a>

## 用途与身份

使用 `Authorization: Bearer` 加完整虚拟密钥，见[地址与鉴权](access.md)。文件操作不消耗模型额度，但会重新校验消费主体、企业状态、密钥有效期、IP 及素材连接权限。管理会话不能替代消费密钥。文件与素材在企业内共享，跨企业不可访问。

| `purpose` | 存储与使用方式 | 生命周期 |
| --- | --- | --- |
| `reference` | 存入企业绑定火山渠道的 TOS，返回临时文件 | 7 天有效，不需要审核 |
| `provider_asset` | 写入企业绑定的火山素材库，返回素材 ID | 审核通过后可引用，按素材删除流程管理 |

两种用途都需要企业配置有效的素材连接。模型要求厂商素材时，先上传 `provider_asset` 并等待 `ready`，不能用普通临时文件替代。平台不会自动把 `reference` 入库。

<a id="media-files-h-9e07e3c0"></a>

## 上传

`POST /media/v1/files` 支持 multipart 文件、Base64 和公网 URL。成功返回 HTTP 201 与扁平 `media.file` 对象。

```bash
curl "$GATEWAY_ORIGIN/media/v1/files" \
  -H "Authorization: Bearer $KEY" \
  -F 'purpose=reference' \
  -F 'name=首帧参考' \
  -F 'file=@first-frame.png;type=image/png'
```

```json
{
  "purpose": "provider_asset",
  "name": "首帧素材",
  "asset_type": "image",
  "url": "https://media.example.com/first-frame.png",
  "wait_seconds": 30
}
```

JSON 上传时 `url` 与 `base64` 二选一；Base64 可以使用包含媒体类型的 Data URL，纯 Base64 可另传 `content_type`。multipart 使用 `file` 部分。大小和媒体类型沿用企业素材 API 的限制；外围请求正文上限 268 MiB 用于容纳最大 200 MiB 媒体的 Base64 表示，并不表示所有媒体类型都能上传到该大小。

`provider_asset` 保留 `name`（1–64 字符）、`group_id`、`asset_type`、`wait_seconds` 等字段。省略素材组使用企业默认组；URL 上传视频或音频时必须声明 `asset_type`。`wait_seconds` 为 0–30 秒，默认 30，只等待审核结果。`reference` 不接受 `group_id` 或 `wait_seconds`。

文件和 Base64 先转存企业私有 TOS 再入库；公网素材 URL 由厂商直接读取。素材库满额时只尝试删除本企业最早且未被生成任务使用的一条素材，再重试一次。同一企业的写操作串行执行，冲突返回 HTTP 409 `unsupported_operation`；应核对原操作结果，不能盲目重复上传。

<a id="media-files-h-9241a488"></a>

## 对象与状态

`id` 是平台目录的不透明文件标识，供 `/files/{id}` 操作及生成的 `file_id` 使用，不能自行解析或拼装。`provider_asset` 另有 `asset_id`，供生成请求引用；两者不能互换。

对象包含 `object: "media.file"`、`purpose`、`status`、`metadata`，以及适用时的 `name`、`asset_type`、`group_id`、`url`、`created_at`、`expires_at`、`asset_id`。媒体类型使用小写。

| `status` | 含义 |
| --- | --- |
| `processing` | 上传或审核尚未确认完成 |
| `ready` | 可以引用 |
| `rejected` | 审核未通过，查看错误原因 |
| `expired` | 临时文件已过期，在列表中可见此状态 |

`check_pending: true` 表示对象已经创建，但后续查询暂未成功；保留 ID 并继续查询，不重新创建。可用的 `error_code`、`error_message` 说明审核或查询问题。旧临时文件缺少上传完成证据时，列表保留待确认；读取时确认存储对象存在后才标记可用，不延长原有到期时间。

<a id="media-files-h-92418ebe"></a>

## 查询、列表与删除

| 方法与路径 | 用途 |
| --- | --- |
| `GET /media/v1/files/{id}` | 查询当前状态；临时文件在剩余有效期内重新签发 URL |
| `GET /media/v1/files?purpose=provider_asset&group_id=…&page=1&page_size=20` | 按用途和素材组分页查询 |
| `DELETE /media/v1/files/{id}` | 删除当前企业的文件或素材 |

`page` 从 1 开始，`page_size` 为 1–100，默认 20。省略 `purpose` 返回两类对象：临时文件按创建时间和 ID 倒序排在前，厂商素材按既有创建时间倒序排在后。提供 `group_id` 时只返回厂商素材，不能与 `purpose=reference` 同时使用。

列表返回 `object: "list"`、`items`、`total`、`page`、`page_size`、`has_more`、`next_page`，末页的 `next_page` 为 `null`。该分页是实时目录，列表期间新增或删除对象可能改变后续页面，应按 ID 去重。

删除成功返回 `{"id":"…","object":"media.file","deleted":true}`。删除失败保留可恢复状态，不把未完成删除宣称成功。查询过期临时文件返回 HTTP 410 `file_expired`；不存在或无当前企业可见记录返回 `file_not_found`。

<a id="media-files-h-39a7b418"></a>

## 文件请求与采集

文件上传、查询、列表和删除直连网关，不进入模型调用正文采集；生成请求中引用的 ID 或 URL 仍按模型调用留存。