# 上传文件

上传一个文件到账号下的素材库。请求体为 `multipart/form-data`，
包含 `file` 字段（必填，二进制）和可选的 `purpose` 字段。

文件以流式方式直接写入对象存储，不会在网关缓冲，单文件上限 500 MB。
支持任意 MIME，服务端按类型归类为 `image` / `video` / `audio` / `file`。

上传后会占用账号 5 GB 存储配额；超过配额的文件仍可上传，但仅保留 24 小时。

## POST /v1/files

> 上传文件

上传一个文件到账号下的素材库。请求体为 `multipart/form-data`，
包含 `file` 字段（必填，二进制）和可选的 `purpose` 字段。

文件以流式方式直接写入对象存储，不会在网关缓冲，单文件上限 500 MB。
支持任意 MIME，服务端按类型归类为 `image` / `video` / `audio` / `file`。

上传后会占用账号 5 GB 存储配额；超过配额的文件仍可上传，但仅保留 24 小时。

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `multipart/form-data`

- **file** `string` **(required)**  
  待上传的文件
- **purpose** `string`  
  可选，业务用途标签，原样回显

### Error Codes

- `201`: 上传成功
- `400`: 
- `401`: 
- `413`: 文件超过 500 MB 上限
- `503`: 当前部署未配置对象存储，无法接受上传