FileHost/docs-site/guide/api.md

API

PicHost 提供 REST 接口与 Twikoo 兼容端点。登录后打开顶栏 API 页：左侧为接口目录与 Token 管理，中间为参数说明与 cURL 示例，右侧可 在线调试 发送请求。

鉴权

所有 REST 接口使用请求头：

Auth-Token: YOUR_TOKEN

Token	获取方式	说明
API Token	登录后 API 页（每账号一个，自动生成）	请求头 Auth-Token；上传与 tagNames 归属该账号
遗留全站 Token	环境变量 API_UPLOAD_TOKEN 或旧版后台配置	仍可用；上传归属首个管理员账号。Twikoo 表单 token 亦支持各账号 API Token

表单上传仍可使用字段 token（Twikoo 协议）。

接口列表

1. 上传图片

POST /api/images/upload

上传单张或多张图片。字段 image 传图片；仍兼容 file、files。存入 images/。

curl -X POST "https://admin.example.com/api/images/upload" \
  -H "Auth-Token: YOUR_TOKEN" \
  -F "image=@./demo.png" \
  -F 'tagNames=["博客","截图"]'

可选表单字段 tagNames：JSON 数组或逗号分隔名称；上传成功后自动打标。存储路径仍为 images/年/月/id.webp，不会因标签创建子目录。

2. 获取图片列表

GET /api/images

分页列出图库。limit 默认 20、最大 100。

curl "https://admin.example.com/api/images?limit=20&page=1" \
  -H "Auth-Token: YOUR_TOKEN"

可选查询参数：

参数	说明
tagIds	逗号分隔的标签 ID，默认 OR（含任一标签）
tagMode	and 时多标签取交集
untagged	1 仅返回无标签图片

响应 items[] 含 tags 数组（id、name、color）。

3. 搜索图片

GET /api/images/search

按文件名或路径关键词搜索，参数 q 必填。

curl "https://admin.example.com/api/images/search?q=demo&limit=20&page=1" \
  -H "Auth-Token: YOUR_TOKEN"

4. 删除图片

DELETE /api/images

通过 key 删除单张，key 为存储路径（如 images/2026/08/xxx.webp）。

curl -X DELETE "https://admin.example.com/api/images?key=images/2026/08/xxxx.webp" \
  -H "Auth-Token: YOUR_TOKEN"

5. 批量删除

POST /api/images/batch-delete

请求体 JSON：{"keys":["images/2026/08/a.webp","images/2026/08/b.webp"]}

curl -X POST "https://admin.example.com/api/images/batch-delete" \
  -H "Auth-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys":["images/2026/08/a.webp","images/2026/08/b.webp"]}'

6. 标签管理

方法	路径	说明
GET	/api/tags	当前用户标签列表（含 imageCount）
POST	/api/tags	创建 { "name": "工作", "color": "#22c55e" }
PATCH	/api/tags/:id	改名称/颜色
DELETE	/api/tags/:id	删除标签（不删图片）
POST	/api/tags/merge	{ "sourceIds": [2,3], "targetId": 1 }

7. 图片打标

方法	路径	说明
POST	/api/images/tags	{ "key": "images/…", "tagIds": [1,2] } 追加
PATCH	/api/images/tags	整体替换标签集合
DELETE	/api/images/tags	key + tagId 移除单个
POST	/api/images/batch-tags	{ "keys": [], "tagIds": [], "action": "add" | "remove" }

GET /api/stats 支持与列表相同的 tagIds / tagMode / untagged 筛选，统计与当前筛选一致。

错误格式

REST 接口返回 JSON，含 code 与 message（如 UNAUTHORIZED、FORBIDDEN、INVALID_REQUEST）。Twikoo 端点使用 EasyImage 兼容 JSON 格式。

权限与可见范围

• 普通用户 Token：列表/搜索/删除仅作用于自己的图片
• 管理员 Token：可访问全部图片
• 全局 Token 上传的图片归属管理员

详见 用户与权限。

Twikoo

POST /api/index.php 见 Twikoo。

相关

• 环境变量 — API_UPLOAD_TOKEN
• 反向代理 — 公网 URL 与 HTTPS