ImageHost · API 文档

鉴权

在请求头中携带 Bearer Token（API Key）：

Authorization: Bearer <your-api-key>

首次启动会自动创建「系统通用 Key」，原始值等于配置中的 ADMIN_PASSWORD（当前环境默认 1314512a）。也可在管理后台创建专用 Key。

程序 / AI 对接请遵循仓库 对接说明.md：默认用通用 Key；需要新目录隔离时先提示用户再创建 Key。

GET /api/health 健康检查

运维探活。另提供兼容路径 GET /api/v1/health，行为相同。无需鉴权。

响应示例 200

{
  "status": "ok",
  "database": "ok",
  "storage": "ok"
}

POST /api/v1/upload 文件上传

以 multipart/form-data 上传图片文件。需鉴权。

表单字段

字段	类型	必填	说明
`file`	file	是	图片文件
`path`	string	否	自定义目录（需 Key 允许自定义路径）

请求示例

curl -X POST "__BASE__/api/v1/upload" \
  -H "Authorization: Bearer <your-api-key>" \
  -F "file=@test.png" \
  -F "path=diy/mxg"

成功响应 201 新建

{
  "success": true,
  "duplicate": false,
  "data": {
    "id": 1,
    "url": "__BASE__/upload/diy/mxg/20260821/172422_ab12cd.jpg",
    "path": "diy/mxg/20260821/172422_ab12cd.jpg",
    "filename": "172422_ab12cd.jpg",
    "sha256": "…",
    "format": "JPEG",
    "mime_type": "image/jpeg",
    "width": 800,
    "height": 600,
    "size": 102400,
    "original_size": 204800,
    "compressed": true,
    "source": "file",
    "created_at": "2026-08-21T19:24:22+08:00"
  }
}

去重命中 200

同一 API Key 下相同 SHA256 图片会返回已有记录，不重复落盘。

{
  "success": true,
  "duplicate": true,
  "data": {
    "id": 1,
    "url": "__BASE__/upload/…",
    "path": "…",
    "filename": "…",
    "sha256": "…"
  }
}

POST /api/v1/upload/url URL 上传

从远程 URL 下载图片后入库。含 SSRF 与下载大小防护。需鉴权。Content-Type: application/json

请求体

字段	类型	必填	说明
`url`	string	是	图片地址
`path`	string	否	自定义目录

请求示例

curl -X POST "__BASE__/api/v1/upload/url" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a.png","path":"main"}'

POST /api/v1/upload/base64 Base64 上传

提交 Base64 编码的图片数据。需鉴权。Content-Type: application/json

请求体

字段	类型	必填	说明
`image`	string	是	纯 Base64，或 `data:image/…;base64,…`
`path`	string	否	自定义目录

请求示例

curl -X POST "__BASE__/api/v1/upload/base64" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"image":"iVBORw0KGgo…","path":"ai"}'

GET /api/v1/images/{image_id} 查询图片

按 ID 获取图片元数据。是否强制鉴权由配置 REQUIRE_API_KEY_FOR_IMAGE_INFO 控制。

路径参数

参数	类型	说明
`image_id`	integer	图片 ID

响应示例 200

{
  "success": true,
  "data": {
    "id": 1,
    "url": "__BASE__/upload/…",
    "path": "…",
    "filename": "…",
    "sha256": "…",
    "format": "JPEG",
    "mime_type": "image/jpeg",
    "width": 800,
    "height": 600,
    "size": 102400,
    "original_size": 204800,
    "compressed": true,
    "source": "file",
    "created_at": "2026-08-21T19:24:22+08:00"
  }
}

DELETE /api/v1/images/{image_id} 删除图片

删除当前 API Key 拥有的图片。需鉴权。

请求示例

curl -X DELETE "__BASE__/api/v1/images/1" \
  -H "Authorization: Bearer <your-api-key>"

响应示例 200

{
  "success": true,
  "message": "Image deleted"
}

错误响应

{
  "success": false,
  "error": {
    "code": "file_too_large",
    "message": "Uploaded file exceeds size limit"
  }
}

常见状态码：400 参数错误、401/403 鉴权失败、404 不存在、413 超限、422 校验失败。

迁移备注

2026-09-25。旧站 img.98lm.com 的图片换到测试域名 https://jpg.090603.xyz 时，不能只换主机名，路径也要改。

同一张图：

以前  https://img.98lm.com/tk_img/upload/20260421/1776756872_1677.jpg
现在  https://jpg.090603.xyz/upload/tk/20260421/1776756872_1677.jpg

主机换成 https://jpg.090603.xyz。
路径 /tk_img/upload/ 换成 /upload/tk/。后面的日期目录和文件名不动。
这是公网入口测试。现网 jpg.98lm.com 在另一台 VPS 上，不要改它，也不要改图床的 PUBLIC_BASE_URL。
新上传的图片以接口返回的 data.url 为准，不要用上面这条旧路径规则去拼。
旧文件从 47.106.67.152:/www/wwwroot/img.98lm.com/tk_img/upload/ 拷到飞牛 /vol4/www/api_imagehost-2020/upload/tk/。正在跑的图床读的是 /vol4/image-host/upload，拷贝目录还没挂进去。2026-09-25 当晚大约 6 万张里到了 7300 多张，拷贝未完成，所以新地址当时还打不开。

说明

相同源图片仅在同一 API Key内按 SHA256 去重。
存储路径形如 upload/{path}/{YYYYMMDD}/{timestamp}_{random6}.ext。
压缩策略、默认目录、是否允许自定义路径由各 API Key 策略决定。
管理后台页面（/admin/*）不在本公开 API 文档范围内。