API 文档 · 图床 img.01ai.space

所有接口必须携带 Token（在管理页或 /www/wwwroot/img.01ai.space/config.php 查看），二选一：

# 方式一（推荐）
X-API-Token: <你的 Token>

# 方式二
Authorization: Bearer <你的 Token>

未带或 Token 错误返回 401：{"success":false,"msg":"unauthorized..."}

接口列表

支持的类型与上限

方法	路径	说明
POST	`/api/upload`	上传文件：图片 / 视频 / 音频 / 文档（multipart 或 raw 二进制）
GET	`/api/list`	文件列表（分页，时间倒序）
POST	`/api/delete`	删除文件
GET	`/api/settings`	读取存储策略（保留天数/空间上限/已用）
POST	`/api/settings`	修改存储策略

分类 `type`	格式	单文件上限
`image` 图片	PNG / JPG / WebP / GIF / BMP / AVIF / HEIC / SVG	20 MB
`video` 视频	MP4 / WebM / MOV / AVI / MKV / FLV	100 MB
`audio` 音频	MP3 / WAV / FLAC / OGG / M4A	50 MB
`file` 文档	PDF / ZIP / TXT	50 MB

类型只信真实内容：服务端探测文件魔数，伪装后缀返回 415
想加类型改 config.php 的 EXT_BY_MIME / SIZE_LIMITS

POST /api/upload — 上传文件

请求（multipart 表单，字段名 file）：

curl -H "X-API-Token: <token>" -F file=@本地图片.png https://img.01ai.space/api/upload
curl -H "X-API-Token: <token>" -F file=@视频.mp4    https://img.01ai.space/api/upload

请求（raw 二进制 body）：

curl -H "Authorization: Bearer <token>" \
     --data-binary @本地图片.png https://img.01ai.space/api/upload

成功响应（200）：

{"success": true, "data": {
  "id": "20260903_143000_ab12cd34ef56.png",     // 删除时用这个 id
  "url": "https://img.01ai.space/i/2026/09/03/20260903_143000_ab12cd34ef56.png",
  "type": "image",                                // image / video / audio / file
  "mime": "image/png",                            // 探测出的真实类型
  "size": 123456, "width": 1024, "height": 768,  // 宽高仅图片有值，其余为 0
  "markdown": "![](https://...)",                 // 图片为 ![]()，其余为 [文件名](链接)
  "html": "<img src=\"...\" />",                   // 按类型给 img/video/audio/a
  "time": 1788421130,
  "cleaned": ["被自动清理的旧文件 id"]            // 本次上传触发的清理（无则为空数组）
}}

GET /api/list — 文件列表

参数：

参数	类型	默认	必填	说明
page	int	1	否	页码，从 1 开始
size	int	50	否	每页条数，最大 100

curl -H "X-API-Token: <token>" "https://img.01ai.space/api/list?page=1&size=50"

响应：

{"success": true, "data": {"total": 2, "page": 1, "size": 50, "items": [
  {"id": "...", "url": "...", "type": "image", "size": 70, "time": 1788421130}
]}}

POST /api/delete — 删除文件

请求（按 id 或 url 均可，二选一）：

curl -H "X-API-Token: <token>" -H "Content-Type: application/json" \
     -X POST -d '{"id":"20260903_143000_ab12cd34ef56.png"}' https://img.01ai.space/api/delete

# 或按 url:
curl -H "X-API-Token: <token>" -H "Content-Type: application/json" \
     -X POST -d '{"url":"https://img.01ai.space/i/2026/09/03/xxx.png"}' https://img.01ai.space/api/delete

响应：

{"success": true, "data": {"id": "20260903_143000_ab12cd34ef56.png"}}
# 不存在 → 404; 格式非法 → 400

GET /api/settings — 读取存储策略

curl -H "X-API-Token: <token>" https://img.01ai.space/api/settings

{"success": true, "data": {
  "retentionDays": 0,                    // 0=永久, 1/7/30 天
  "storageGb": 2,                        // 2/5/8 GB
  "updatedAt": 1788423177,
  "storageUsedBytes": 0,              // 当前已用
  "storageLimitBytes": 2147483648    // 空间上限
}}

POST /api/settings — 修改存储策略

请求：

curl -H "X-API-Token: <token>" -H "Content-Type: application/json" \
     -X POST -d '{"retentionDays":30,"storageGb":5}' https://img.01ai.space/api/settings

参数：

参数	可选值	必填	说明
retentionDays	`0` / `1` / `7` / `30`	是	`0` = 永久保留（只按空间清理）
storageGb	`2` / `5` / `8`	是	总空间上限，超出时从最旧开始删

生效规则：

保存后立即生效；改小保留天数时，会把已超龄的图一并清理（响应 cleaned 数组列出）
上传接口每次调用后也会自动触发清理（超龄 + 超空间）

限制与约定

只收真实文件（见上方类型表），超分类上限返回 413，类型不识别返回 415
服务端探测真实内容（getimagesize + 文件头魔数），伪装后缀会被拒绝
文件 URL 公网可直接访问（/i/年/月/日/<文件名>），带一年长缓存；视频/音频支持 Range 分段播放
SVG 外链带 CSP sandbox 头，内嵌脚本不会执行
图片类客户端（PicGo / ShareX / Typora）行为不变，照旧传图片即可
删除不可恢复

客户端接入示例

PicGo

安装 web-uploader 插件，新建自定义图床：

POST URL: /api/upload
表单字段名: file
自定义请求头: X-API-Token: <token>
JSON 路径: data.url

ShareX

Request URL: https://img.01ai.space/api/upload
File form name: file
Headers: X-API-Token: <token>
URL 取: $json:data.url$

Typora

设置 → 图像 → 上传服务选 PicGo(app)，在 PicGo 里配上面那组参数即可。

浏览器 fetch

const fd = new FormData();
fd.append('file', fileInput.files[0]);
const r = await fetch('/api/upload', {
  method: 'POST',
  headers: { 'X-API-Token': token },
  body: fd
});
const j = await r.json();
// j.data.url 即外链

鉴权