imgLi 文档imgLi 文档
GitHub

上传 API

上传 API

干净的 HTTP 上传接口 + Bearer API Token，便于脚本、PicGo、CI。自 v0.2 起提供 imgli upload；v0.3 起另有 imgli import-dir 批量导入，以及分享/相册/缩略相关 API。

创建 Token

登录 → 设置 → API Token → 新建。
Scope 选 upload（仅上传）或 full。
明文只显示一次，请立即保存到密码管理器。

上传

curl -X POST https://your-host/api/v1/upload \
  -H "Authorization: Bearer <API_TOKEN>" \
  -F file=@shot.png \
  -F visibility=public
项值
MethodPOST
Content-Typemultipart/form-data
文件字段名file（必须）
鉴权Authorization: Bearer <token>
可选表单visibility=public | private（默认随用户偏好）

成功响应（节选）

{
  "status": true,
  "message": "ok",
  "data": {
    "key": "xxxxxxxxxxxx",
    "name": "shot.png",
    "instant": false,
    "links": {
      "url": "https://your-host/i/xxxxxxxxxxxx.png",
      "markdown": "![shot.png](https://your-host/i/xxxxxxxxxxxx.png)",
      "html": "<img src=\"https://your-host/i/xxxxxxxxxxxx.png\" alt=\"shot.png\">",
      "bbcode": "[img]https://your-host/i/xxxxxxxxxxxx.png[/img]",
      "thumbnail_url": "https://your-host/t/xxxxxxxxxxxx.jpg"
    }
  }
}

取直链：JSON Path data.links.url。

官方 CLI：imgli upload

export IMGLI_BASE_URL=https://your-host
export IMGLI_TOKEN='你的 token'
imgli upload ./shot.png --format url
# --format markdown|json；也可从 stdin 读

ShareX / uPic 等自定义上传配置见仓库 docs/integrations/（与本页 API 形状一致：data.links.url）。公开图可使用分享页路径 /s/{key}（产品 SPA）。

常见错误

HTTP含义
401Token 无效 / 未带 Bearer
403游客上传关闭且未登录（或无权限）
413超过用户组大小上限
415扩展名不允许（ext_not_allowed），或当前构建无法解码 HEIC（heic_unsupported：请用官方 Docker / make build-vips，且组策略允许 heic/heif）
429限速（关注 Retry-After）

无 Token 游客上传

同一 URL 可不带 Authorization，但受游客组策略约束（限速、是否开启）。
不要给常驻图床工具配游客模式。

自测清单

export IMGLI_TOKEN='你的 token'
curl -sS -X POST "https://your-host/api/v1/upload" \
  -H "Authorization: Bearer $IMGLI_TOKEN" \
  -F 'file=@/path/to/test.png' \
  -F 'visibility=public' | jq .
# 浏览器打开 data.links.url

压测脚本（仓库）：scripts/loadtest.py write --token …
健康检查示例：deploy/ops/health-check.sh

相关：分享与外链 · OIDC · Webhook · PicGo · 公共实例 · 仓库 docs/integrations/。

可选上传字段（节选）

字段说明
visibilitypublic 或 private
expires_in秒；0 或不传=永久
max_views0=不限；>0 对非属主限次
access_password访问口令（仅提交时明文；永不回显）
album_id / policy_id可选

CLI：imgli import-dir

export IMGLI_BASE_URL=https://your-host
export IMGLI_TOKEN='你的 token'
imgli import-dir ./photos
imgli import-dir -dry-run ./photos
imgli import-dir -visibility private ./inbox

批量走同一套 POST /api/v1/upload。详见仓库 docs/integrations/README.md。

直链与缩略尺寸

路径说明
GET /i/{key}.{ext}原图（过访问控制）
GET /t/{key}.jpg默认缩略图
GET /t/{key}.jpg?w=120 … 1600白名单边长：120, 200, 240, 400, 480, 800, 960, 1600；其它值 HTTP 400

嵌入论坛/Markdown 可用 ?w=400 或 ?w=960 控制预览宽度。HEIC 上传成功后 {ext} 是 jpg 或 webp，不会是 heic。

分享与公开相册 API

方法路径说明
GET/api/v1/s/{key}公开分享元数据；有口令且未解锁时 password_required
POST/api/v1/s/{key}/unlock体 {"password":"..."}，成功写解锁 cookie
GET/api/v1/a/{id}公开相册元数据
GET/api/v1/a/{id}/images公开相册图片列表（cursor）

直链 Header 解锁：X-Image-Password。产品说明见 分享与外链。

Webhook 与 OIDC

出站事件：Webhook。企业 SSO：OIDC。

最后更新: 2026-08-27