对外开放 API

用账号密码换一个 token，之后带着 token 就能上传图片并拿到直链。适合脚本、CI、截图工具或编辑器插件调用，不需要浏览器、也不需要登录本工作台。

无需登录即可阅读 Bearer 认证 token 默认 24 小时单进程运行

概览

整个流程只有三步：

用图床账号密码调用 POST /api/token，拿到 token；
带着 token 调用 POST /api/upload/token 上传图片，返回直链、缩略图等地址；
不再需要时调用 POST /api/token/revoke 吊销，服务端会同时关闭这次登录的会话。

token 与图床会话是一一对应的。服务端在签发 token 时已经把这次登录的 cookies 与 auth_token 缓存下来，后续上传直接复用，不会每次重新登录。同一账号 + 同一密码在有效期内再次申请，会拿回同一个 token。

认证方式

除获取 token 的接口外，其余接口都要带 token，两种写法等价：

HTTP 请求头

Authorization: Bearer <token>
# 或者
X-Token: <token>

token 缺失、写错或过期，都会返回 401，需要重新调用获取 token 的接口。

响应结构

所有接口返回同一层包装，业务数据放在 data 里：

统一结构

{
  "code": 0,
  "msg": "",
  "data": { }
}

字段	类型	说明
code	number	`0` 表示成功；其他值表示失败，取值与 HTTP 状态码一致（400 / 401 / 404 / 422 / 500）
msg	string	成功时为空字符串，失败时是可读的原因
data	object / null	成功时是业务数据，失败时固定为 `null`

HTTP 状态码仍保留语义（成功 200，失败 4xx / 5xx）。判断结果请以 code 为准，data 只在 code === 0 时可信。

获取 token

POST/api/token

用图床账号密码换取 token。账号密码只用于这一次登录，服务端不保存密码明文。

请求体（JSON）

字段	类型	说明
username	string 必填	用户名或注册邮箱
password	string 必填	登录密码

curl

curl -s -X POST __BASE__/api/token \
  -H 'Content-Type: application/json' \
  -d '{"username":"你的账号","password":"你的密码"}'

响应

200 OK · application/json

{
  "code": 0,
  "msg": "",
  "data": {
    "token": "9Yk3v...（43 个字符）",
    "token_type": "Bearer",
    "username": "your_name",
    "userid": "AbCdEf",
    "expires_in": 86400,
    "cached": false
  }
}

字段	说明
token	后续请求使用的凭证，只在服务端内存中保存
expires_in	剩余有效秒数，默认 86400（24 小时）
cached	`true` 表示命中了已有会话，没有重新登录

上传图片

POST/api/upload/token

用 token 上传一张图片，返回可直接使用的链接。请求体是 multipart/form-data。

请求参数

字段	类型	说明
file	file 必填	图片文件，jpg / png / webp / gif / bmp，单张不超过 5 MB
album_id	string 可选	目标相册的编码 ID（相册链接 `/album/Xy9KmN` 末尾那段）。留空则不放入相册
title	string 可选	图片标题，留空由站点自动命名
nsfw	0 / 1 可选	是否标记为不安全内容，默认 0

curl

TOKEN="9Yk3v..."

curl -s -X POST __BASE__/api/upload/token \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./screenshot.png" \
  -F "album_id=Xy9KmN" \
  -F "title=首页截图"

响应

200 OK · application/json

{
  "code": 0,
  "msg": "",
  "data": {
    "status": "ok",
    "filename": "screenshot.png",
    "image": {
      "id": "abc123",
      "url": "https://s41.ax1x.com/2026/11/08/abc123.png",
      "thumb_url": "https://s41.ax1x.com/2026/11/08/abc123.th.png",
      "medium_url": "https://s41.ax1x.com/2026/11/08/abc123.md.png",
      "viewer_url": "https://imgchr.com/i/abc123",
      "title": "首页截图",
      "album_id": "Xy9KmN",
      "album_name": "项目截图"
    }
  }
}

image.url 是原始直链，image.medium_url 是宽度 680px 左右的中等图，image.viewer_url 是图床的查看页。

完整脚本示例

登录一次、上传一张、取出直链，用 jq 解析响应：

shell

BASE="__BASE__"

TOKEN=$(curl -s -X POST "$BASE/api/token" \
  -H 'Content-Type: application/json' \
  -d '{"username":"你的账号","password":"你的密码"}' | jq -r '.data.token')

curl -s -X POST "$BASE/api/upload/token" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./screenshot.png" | jq -r '.data.image.url'

吊销 token

POST/api/token/revoke

立即让 token 失效，并关闭它对应的图床会话。适合在临时脚本结束或怀疑泄露时调用。

curl

curl -s -X POST __BASE__/api/token/revoke \
  -H "Authorization: Bearer $TOKEN"

# {"revoked": true}

token 不存在或已过期时返回 401。

错误码

状态码	含义	常见原因
200	成功	—
400	请求被拒绝	账号或密码错误；图片超过 5 MB；格式不支持；图床站点拒绝
401	未通过认证	没带 token、token 写错、token 已过期或被吊销
429	请求过于频繁	换 token 或登录次数超过限流阈值，稍后再试
422	参数不完整	缺少 `username` / `password`，或上传时没有 `file`

错误响应统一是 {"code": 非0, "msg": "原因", "data": null}，msg 可以直接展示给用户。

401 示例

{"code": 401, "msg": "token 无效或已过期，请重新调用 POST /api/token", "data": null}

注意事项

token 存在进程内存里。服务重启后全部失效；也不要用多进程（--workers）运行，否则各进程的 token 表不互通。
有效期默认 24 小时，可用环境变量 IMGCHR_TOKEN_TTL 调整（单位秒）。
同账号同密码会复用同一 token，避免脚本反复登录触发站点风控。想强制换新，先吊销旧 token。
换 token 有频率限制：默认每 IP 10 次 / 10 分钟，超出返回 429，可用 IMGCHR_LOGIN_RATE_LIMIT 与 IMGCHR_LOGIN_RATE_WINDOW 调整。
token 等同于账号的上传权限，公网部署请务必走 HTTPS，并限制 /api/token 的访问频率。
图片格式与大小限制跟随站点：jpg / png / webp / gif / bmp，单张 ≤ 5 MB。游客上传的图片会被站点清理，请务必用已登录账号的 token。
请遵守图床站点的服务条款，避免高频批量上传。

接口的机器可读描述在 /openapi.json，交互测试可打开 /docs。