# ImgBox 完整 Agent 参考

分页版本见 https://imgly.net/llms.txt。本文件把面向 Agent 的信息集中在一处。

## 认证

免注册。公开上传不需要任何凭据，带上身份 token 只是为了让上传归属于你、
从而可以删除。

    X-User-Token: <token>

token 由浏览器本地生成，UI 可导出身份文件（token + 上传历史）用于备份与迁移。
身份文件等同于密码：持有者可以永久删除该身份名下的任何文件。

## 上传

    POST /api/upload
    Content-Type: multipart/form-data
    字段：file

返回 `files[]`，每项含 `url`、`name`、`original_name`；视频另有
`play_url` 与 `variants_pending`。

大文件改用 Tus：

    POST /api/tus/files
    Tus-Resumable: 1.0.0
    Upload-Length: <字节数>

随后对返回的 `Location` 反复发 `PATCH` 并带上递增的 `Upload-Offset`。
分块越大越快：每次请求有约 0.27s 的固定开销，所以宁可少发几次。

## 删除

    DELETE /api/v1/delete
    X-User-Token: <token>
    Content-Type: application/json
    {"path": "/i/2026/10/03/ab12cd34.jpg"}

必须是该文件的属主身份，否则返回 404。删除不可逆。

## 其他接口

* `GET /api/client-hints`：地区与单文件体积上限
* `GET /api/public-folders`、`GET /api/public-gallery`：公开合集与广场
* `POST|GET|PATCH|DELETE /api/folders/*`：合集管理，需 `X-User-Token`
* `GET /healthz`：存活探针；`GET /api/health/deep`：磁盘/内存/接口检查

## 已知边界

* 匿名上传的文件无法删除。
* 视频衍生是异步生成的，上传后不是立刻可取。
* 入口限速，突发请求会收到 429，应退避重试。

联系：imgly@proton.me