◤ NEON.IMG ◢ // API 文档

// SERVER INFO //

版本--

单文件上限--

游客模式--

自动审核--

支持格式--

// AUTHENTICATION //

通过账号密码登录获取 JWT，用于浏览器端 API 调用。7 天有效，过期需重新登录。

# 获取 JWT
curl -X POST http://your-domain/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"USERNAME","password":"PASSWORD"}'

# 响应 { "code":0, "data":{ "jwt":"eyJ...", ... } }

# 使用 JWT 调用需要鉴权的接口
curl http://your-domain/api/list \
  -H "Authorization: Bearer eyJ..."

登录后在用户面板获取 API Token，用于 PicGo、Typora、Obsidian 等外部工具直传。长期有效，可随时重置。

# 使用 API Token 上传（请求头 x-upload-token）
curl -X POST http://your-domain/api/upload \
  -H "x-upload-token: YOUR_API_TOKEN" \
  -F "files=@image.png"

// API ENDPOINTS //

认证

POST /api/auth/register 公开

注册新账号。username 为 3~20 位字母数字下划线，password 至少 6 位。

curl -X POST http://your-domain/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"123456"}'

{ "code": 0, "data": { "username": "user", "apiToken": "xxx..." } }

POST /api/auth/login 公开

登录并返回 JWT（7 天有效）和 API Token。

curl -X POST http://your-domain/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user","password":"123456"}'

{ "code": 0, "data": { "jwt": "eyJ...", "username": "user", "apiToken": "xx..." } }

GET /api/auth/me JWT

获取当前登录用户的用户名和 API Token。

curl http://your-domain/api/auth/me \
  -H "Authorization: Bearer "

{ "code": 0, "data": { "username": "user", "apiToken": "xx..." } }

POST /api/auth/reset-token JWT

重置当前用户的 API Token，旧 Token 立即失效。

curl -X POST http://your-domain/api/auth/reset-token \
  -H "Authorization: Bearer "

{ "code": 0, "data": { "apiToken": "new_token..." } }

图片上传

POST /api/upload JWT / Token

上传图片（需鉴权）。multipart/form-data，字段名 files，单次最多 10 张，单文件最大 20MB。支持 JPG / PNG / GIF / WEBP / SVG。

curl -X POST http://your-domain/api/upload \
  -H "Authorization: Bearer " \
  -F "files=@image.png" \
  -F "files=@photo.jpg"

{ "code": 0, "data": [{ "id": "...", "url": "http://your-domain/i/...", ... }] }

POST /api/guest/upload 公开

游客上传（无需鉴权）。仅支持 JPG / PNG / WEBP，单文件最大 10MB，单次最多 3 张。图片保留 30 天后自动清理，每日每 IP 限量。

curl -X POST http://your-domain/api/guest/upload \
  -F "files=@image.png"

{ "code": 0, "data": [{ "id": "...", "url": "http://your-domain/i/...", "expiresAt": "..." }] }

图库管理

GET /api/list JWT

获取当前用户的图片列表（不含已拒绝和他人数据）。

curl http://your-domain/api/list \
  -H "Authorization: Bearer "

{ "code": 0, "data": [{ "id": "...", "name": "image.png", "url": "...", "tags": [] }] }

PATCH /api/image/:id/rename JWT

重命名图片（仅更新元数据，不改实际文件名）。中文/字母/数字/空格/连字符/下划线/点，最长 100 字符。

curl -X PATCH http://your-domain/api/image/ID.png/rename \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{"name":"new-name.png"}'

{ "code": 0, "data": { "id": "ID.png", "name": "new-name.png" } }

POST /api/image/:id/tags JWT

设置图片标签（覆盖式）。每个标签 1~20 字符，中文/字母/数字/下划线/连字符，最多 10 个。

curl -X POST http://your-domain/api/image/ID.png/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{"tags":["截图","参考图"]}'

{ "code": 0, "data": { "id": "ID.png", "tags": ["截图","参考图"] } }

DELETE /api/image/:id/tags/:tag JWT

删除图片的单个标签。:tag 参数使用 encodeURIComponent 编码。

curl -X DELETE http://your-domain/api/image/ID.png/tags/%E6%88%AA%E5%9B%BE \
  -H "Authorization: Bearer "

{ "code": 0 }

DELETE /api/image/:id JWT

删除图片（软删除，移入回收站，30 天后可永久清除）。

curl -X DELETE http://your-domain/api/image/ID.png \
  -H "Authorization: Bearer "

{ "code": 0, "msg": "已移入回收站" }

回收站

GET /api/trash JWT

获取当前用户的回收站列表（含剩余天数字段 daysLeft）。

curl http://your-domain/api/trash \
  -H "Authorization: Bearer "

POST /api/restore/:id JWT

从回收站恢复图片到图库。

curl -X POST http://your-domain/api/restore/ID.png \
  -H "Authorization: Bearer "

{ "code": 0, "msg": "已恢复" }

DELETE /api/purge/:id JWT

永久删除图片（不可恢复，会删除磁盘文件）。

curl -X DELETE http://your-domain/api/purge/ID.png \
  -H "Authorization: Bearer "

统计 & 信息

GET /api/stats/me JWT

获取当前用户的统计数据：图片总数、存储量、本月上传、近 7 天趋势。

curl http://your-domain/api/stats/me \
  -H "Authorization: Bearer "

{ "code": 0, "data": { "totalImages": 5, "totalSize": 45718623, ... } }

GET /api/info 公开

获取服务基本信息（版本号、上限配置、功能开关），无需鉴权。

curl http://your-domain/api/info

{ "code": 0, "data": { "version": "1.4.0", "maxFileSize": 20971520, ... } }

// PICGO INTEGRATION //

通过 PicGo 的 web-uploader 插件接入 NEON.IMG，支持快捷上传和自动生成链接。

配置步骤

1. 登录 NEON.IMG，点击 HUD 顶栏用户名 → 复制「API TOKEN」
2. 在 PicGo 中安装 web-uploader 插件（或使用内置 Custom 图床）
3. 填写以下配置参数：

API URL:      http://your-domain/api/upload
Request Header: x-upload-token: YOUR_API_TOKEN
Response Key:  data[0].url

限制

· 支持格式：JPG / PNG / GIF / WEBP / SVG
· 单文件最大 20MB
· 单次最多 10 张
· 游客上传最大 10MB，保留 30 天
· API Token 在用户面板可随时重置