# 上传文件

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

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

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

## POST /v1/files

> Upload a file

Upload a file to the caller's storage. The body is
`multipart/form-data` with a required `file` field and optional
`purpose` label.

The upload is streamed straight into object storage (no gateway
buffering). Hard cap: 500 MB per file. Any MIME is accepted;
the server classifies the row as `image`, `video`, `audio`, or
`file` based on the Content-Type.

Uploads count against the account's 5 GB storage quota.
Overages still upload successfully but are retained only 24 h.

### Authentication

`Authorization: Bearer tr-xxx`

### Request Body

Content-Type: `multipart/form-data`

- **file** `string` **(required)**  
  File content
- **purpose** `string`  
  Optional label echoed back on the response

### Error Codes

- `201`: Upload succeeded
- `400`: 
- `401`: 
- `413`: File exceeds the 500 MB limit
- `503`: This deployment is not configured for uploads