ImageHost · API 文档

鉴权

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

Authorization: Bearer <your-api-key>

首次启动会自动创建「系统通用 Key」，原始值等于配置中的 ADMIN_PASSWORD。也可在管理后台创建专用 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 "http://jpg.98lm.com/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": "http://jpg.98lm.com/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": "http://jpg.98lm.com/upload/…",
    "path": "…",
    "filename": "…",
    "sha256": "…"
  }
}

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

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

请求体

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

请求示例

curl -X POST "http://jpg.98lm.com/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 "http://jpg.98lm.com/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": "http://jpg.98lm.com/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 "http://jpg.98lm.com/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 校验失败。

说明

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