API REFERENCE

API 文档

版本化接口、第三方上传 Token、图库读取与后台操作接口的完整说明。所有示例把 https://your-domain.com 换成你自己实例的域名。

版本化 API 总览

上传	`POST /api/v1`
图库	`GET /api/v1/list`，支持分页、搜索和排序
导出	`GET /api/v1/export`，支持分页或 `all=1` 全量导出
后台操作	`POST /api/v1/action`，支持压缩、WebP、AVIF、删除
鉴权	`X-API-Key: <token>` 或 `Authorization: Bearer <token>`
文件字段	`image` / `image[]` / `file` / `files[]`
返回	`results[]`，逐文件给出 `status` / `url` / `thumbnail_url` / `processing`

Token 在哪里创建：登录 LitePic 后台 → 设置 → 账号 → 新建 API Token。Token 只在创建时显示一次，撤销后立即失效。

cURL 示例

实例域名替换成你自己的，Token 替换成后台创建的 ltp_ 开头的字符串。

上传多张图片

用 multipart/form-data 上传，image[] 字段重复出现表示多张。

POST /api/v1· bash

curl -X POST "https://your-domain.com/api/v1" \
  -H "Authorization: Bearer ltp_xxxxxxxxx" \
  -F "image[]=@/path/a.jpg" \
  -F "image[]=@/path/b.png"

成功返回示例

每张图独立 status，processing 字段记录后处理（压缩 / WebP / AVIF / R2 同步）的每一步结果。

JSON 响应· json

{
  "status": "success",
  "results": [
    {
      "status": "success",
      "filename": "20260227_xxx.webp",
      "original_name": "demo.jpg",
      "url": "https://your-domain.com/uploads/2026/02/20260227_xxx.webp",
      "thumbnail_url": "https://your-domain.com/uploads/2026/02/.thumbs/20260227_xxx.webp",
      "processing": {
        "auto_compress": {"enabled": true, "compressed": true, "method": "imagemagick"},
        "auto_webp": {"enabled": true, "created": true},
        "original_deleted": true,
        "final_filename": "20260227_xxx.webp"
      }
    }
  ]
}

导出全部图片

用于迁移 / 备份场景，all=1 关闭分页一次性返回完整列表。

GET /api/v1/export?all=1· bash

curl "https://your-domain.com/api/v1/export?all=1" \
  -H "Authorization: Bearer ltp_xxxxxxxxx"

功能覆盖

以下接口均有后端实现。普通上传 Token 可上传和读取导出，图库列表与压缩、转换、删除等后台操作需要管理员主密钥或登录态。

能力	请求	权限
上传图片	`POST /api/v1`	上传 Token / 管理员
图库列表	`GET /api/v1/list?page=1&per_page=20`	管理员主密钥 / 管理员登录
迁移导出	`GET /api/v1/export?all=1`	上传 Token / 管理员
图片处理	`POST /api/v1/action`	管理员主密钥 / 管理员登录

后台图片操作接口

页面内调用会附带 csrf_token；外部脚本需使用管理员主密钥。不建议使用普通上传 Token 执行后台操作 —— 权限不够会直接 403。

操作	请求字段	说明
压缩	`action=compress, file=xxx.jpg, csrf_token=...`	仅支持 JPG/JPEG/PNG，返回压缩比例和体积变化。
转 WebP	`action=webp, file=xxx.png, csrf_token=...`	支持 JPG/JPEG/PNG/GIF，成功后返回新文件 URL。
转 AVIF	`action=avif, file=xxx.jpg, csrf_token=...`	支持 JPG/JPEG/PNG/GIF，需 PHP 8.1+ 且 GD 支持 AVIF。
删除	`action=delete, file=xxx.webp, csrf_token=...`	删除原图并清理缩略图，远程对象进入 24 小时延迟删除队列。

所有 action 接口共用 POST /api/v1/action endpoint，请求体统一 form-data 格式。

WordPress 插件对接

在插件设置中填写图床地址（例如 https://your-domain.com）。
填写 API Token，并点击「连接测试」确认连通。
开启「WordPress 上传同步到图床」。
在文章编辑器中使用「插入图床图片」按钮，选择已上传图片或直接上传。

推荐在插件中使用 /api/v1 作为上传入口 —— 返回结构稳定且带处理报告，老的 /api/upload.php 已不再维护。