初春图床 API 文档#

图床对外提供的 HTTP 接口，覆盖上传、图库管理、标签、存储桶、统计与系统设置。

基础说明#

接口地址：以下接口路径均需拼接你的站点域名，例如 https://img.example.com，文中只列出路径部分（如 /api/images/random）。
统一返回格式：所有接口均返回 JSON，结构固定为：

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {}
5
}

code 为 200 表示成功，4xx / 5xx 表示失败；data 为具体数据或 null。

Token 认证：标注「需要 Token」的接口，请在请求头携带：

1
Authorization: Bearer <你的 API Token>

Token 获取方式：后台 → 系统设置 → API Token（支持自定义）。使用前需在后台开启「启用 API」。

接口目录#

分组	接口
公共接口（无需 Token）	#1 随机图 · #2 登录设置 · #3 SEO 设置
认证与用户	#4 用户信息 · #5 修改账户信息
上传	#6 上传配置 · #7 图片上传 · #8 批量上传 · #9 URL 上传
图片管理	#10 图片列表 · #11 图片详情 · #12 删除图片 · #13 添加标签 · #14 删除标签 · #15 批量添加标签 · #16 批量删除标签 · #17 访问源 · #18 批量访问源
标签	#19 获取标签 · #20 添加标签 · #21 更新标签 · #22 删除标签
存储桶	#23 存储桶列表 · #24 全部存储桶 · #25 新增存储桶 · #26 更新存储桶 · #27 删除存储桶 · #28 启用停用 · #29 测试连接
统计	#30 仪表板统计 · #31 图片统计
系统设置	#32 获取设置 · #33 更新设置 · #34 随机图配置
其他	#35 图片外链水印

一、公共接口（无需 Token）#

1. 获取随机图#

1
GET /api/images/random

认证：无需

参数

参数	类型	说明
tag	text	标签分类
model	json / image	返回数据类型（json 或图片流）
limit	int	返回数量限制（默认 1）

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": [
5
    {
6
      "image": "20250310-142106.webp",
7
      "url": "http://localhost:8080/uploads/2026/01/20250310-142106.webp"
8
    }
9
  ]
10
}

2. 获取登录设置#

1
GET /api/settings/login

认证：无需

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "verify_method": "cappow",
6
    "pow_verify": false,
7
    "turnstile_site_key": "",
8
    "tourist": true,
9
    "start_register": false,
10
    "oidc_enabled": false,
11
    "cas_enabled": false
12
  }
13
}

3. 获取 SEO 设置#

1
GET /api/settings/seo

认证：无需

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "seo_title": "初春图床",
6
    "seo_description": "初春图床，一个免费、稳定、高效的图床服务",
7
    "seo_keywords": "初春网络,雾创岛,初春图床,图床,免费,稳定,高效",
8
    "seo_icp": "",
9
    "public_security": "",
10
    "seo_icon": ""
11
  }
12
}

二、认证与用户（需要 Token）#

4. 获取用户信息#

1
GET /api/user/status

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "已登录",
4
  "data": {
5
    "logged_in": true,
6
    "user_id": 1,
7
    "username": "admin"
8
  }
9
}

5. 修改账户信息#

1
POST /api/account/change

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "current_password": "旧密码",
3
  "new_password": "新密码（可留空，仅修改用户名时留空）",
4
  "new_username": "新用户名（可留空，仅修改密码时留空）"
5
}

返回示例

1
{
2
  "code": 200,
3
  "message": "修改成功，请重新登录",
4
  "data": null
5
}

注意：修改成功后当前会话会失效，需重新登录。

三、上传（需要 Token）#

6. 获取上传配置#

1
GET /api/uploadConfig

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "default_bucket": 1,
6
    "buckets": [
7
      { "id": 1, "name": "默认存储", "type": "default" },
8
      { "id": 2, "name": "R2", "type": "r2" }
9
    ],
10
    "tags": [
11
      { "id": 1, "name": "TG" }
12
    ]
13
  }
14
}

7. 图片上传（单张）#

1
POST /api/upload

认证：需要

请求数据类型：multipart/form-data

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
file	file	图片文件
bucket_id	int	存储桶 ID（可选，默认使用系统默认存储）

8. 图片批量上传#

1
POST /api/upload/images

认证：需要

请求数据类型：multipart/form-data

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
file[]	file[]	图片文件列表
bucket_id	int	存储桶 ID（可选）

返回示例（#7、#8 共用）

1
{
2
  "code": 200,
3
  "message": "上传成功",
4
  "data": {
5
    "count": 1,
6
    "files": [
7
      {
8
        "success": true,
9
        "message": "上传成功",
10
        "url": "/uploads/2026/03/1899494c7aaf90d0839.webp",
11
        "storage": "default",
12
        "filename": "1899494c7aaf90d0839.webp",
13
        "file_size": 170092,
14
        "mime_type": "image/webp",
15
        "width": 2640,
16
        "height": 1488,
17
        "created_at": "2026-03-03 17:02:01"
18
      }
19
    ]
20
  }
21
}

9. URL 远程上传图片#

1
POST /api/images/url

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "url": "https://example.com/image.jpg",
3
  "tag_id": 1,
4
  "bucket_id": 1
5
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
url	string	图片 URL（必填）
tag_id	int	标签 ID（可选）
bucket_id	int	存储桶 ID（可选，默认 1）

返回示例

1
{
2
  "code": 200,
3
  "message": "URL 图片上传成功",
4
  "data": null
5
}

四、图片管理（需要 Token）#

10. 获取图片列表#

1
GET /api/images

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
page	int	页码
limit	int	每页数量
sort_order	desc / asc	排序方式
order_by	text	排序字段（如 created_at）
role	admin / guest / user	角色筛选
tags	text	标签 ID，支持多个用逗号分隔（如 `0,1,2`）
bucket_id	int	存储桶 ID
search	text	按文件名模糊搜索

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "images": [
6
      {
7
        "id": 32,
8
        "url": "/uploads/2026/01/1889534a80182ddc297.webp",
9
        "thumbnail": "",
10
        "filename": "1889534a80182ddc297.webp",
11
        "file_size": 117818,
12
        "mimeType": "image/webp",
13
        "width": 640,
14
        "height": 640,
15
        "storage": "default",
16
        "bucket_id": 1,
17
        "user_id": 2873846347613367382,
18
        "md5": "ab34b8d2a98f7f9c6cab0ed633100790",
19
        "uuid": "35b3fcf8-cbbe-46db-88c0-b369da0c7213",
20
        "created_at": "2026-01-10T17:05:08.1640839+08:00",
21
        "tags": [{ "id": 0, "name": "默认" }]
22
      }
23
    ],
24
    "limit": 20,
25
    "page": 1,
26
    "total": 1,
27
    "total_pages": 1
28
  }
29
}

11. 获取图片详情#

1
GET /api/images/:id

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	图片 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "获取图片详情成功",
4
  "data": {
5
    "id": 1,
6
    "url": "/uploads/2025/12/18841fa146649ddc582.webp",
7
    "thumbnail": "/uploads/2025/12/thumbnails/18841fa146649ddc582.webp",
8
    "filename": "18841fa146649ddc582.webp",
9
    "file_size": 119370,
10
    "mimeType": "image/webp",
11
    "width": 640,
12
    "height": 640,
13
    "storage": "default",
14
    "bucket_id": 1,
15
    "user_id": 1,
16
    "md5": "fe5ba8b5ad6cc6b44ffc0471958ca417",
17
    "uuid": "admin",
18
    "created_at": "2025-12-24T18:22:11.3717763+08:00"
19
  }
20
}

12. 删除图片#

1
DELETE /api/images/:id

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	图片 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "删除成功",
4
  "data": null
5
}

13. 添加图片标签#

1
POST /api/images/tag

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "id": 1,
3
  "tags": 1
4
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	图片 ID
tags	int	标签 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "标签添加成功",
4
  "data": null
5
}

14. 删除图片标签#

1
DELETE /api/images/tag

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	图片 ID
tags	int	标签 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "标签删除成功",
4
  "data": null
5
}

15. 批量添加图片标签#

1
POST /api/images/tags

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "image_ids": [1, 2, 3],
3
  "tag_id": 1
4
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
image_ids	[]int	图片 ID 列表
tag_id	int	标签 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "批量添加标签成功",
4
  "data": null
5
}

16. 批量删除图片标签#

1
DELETE /api/images/tags

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
image_ids	[]int	图片 ID 列表
tag_id	int	标签 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "批量删除标签成功",
4
  "data": null
5
}

17. 更新图片访问源#

切换单张图片对外访问所用的成功存储副本（不改动原图元数据，也不删除其它副本）。

1
PUT /api/images/:id/access-source

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "bucket_id": 2
3
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	图片 ID（路径参数）
bucket_id	int	目标存储桶 ID（该图片必须已在其中存在成功副本）

返回示例

1
{
2
  "code": 200,
3
  "message": "图片访问源已更新",
4
  "data": { "image_ids": [1], "bucket_id": 2 }
5
}

18. 批量更新图片访问源#

1
PUT /api/images/access-source

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "image_ids": [1, 2, 3],
3
  "bucket_id": 2
4
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
image_ids	[]int	图片 ID 列表
bucket_id	int	目标存储桶 ID（所有图片均需已存在该源的成功副本）

返回示例

1
{
2
  "code": 200,
3
  "message": "批量访问源已更新",
4
  "data": { "image_ids": [1, 2, 3], "bucket_id": 2 }
5
}

五、标签（需要 Token）#

19. 获取标签#

1
GET /api/tags

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "list": [{ "id": 1, "name": "TG" }],
6
    "total": 1
7
  }
8
}

20. 添加标签#

1
POST /api/tags

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "name": "新标签"
3
}

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": { "id": 2, "name": "新标签" }
5
}

21. 更新标签#

1
PUT /api/tags/:id

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "name": "修改后的标签名"
3
}

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": { "id": 2, "name": "修改后的标签名" }
5
}

22. 删除标签#

1
DELETE /api/tags/:id

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	标签 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {}
5
}

六、存储桶（需要 Token）#

23. 获取存储桶列表#

返回所有存储桶的简要信息。

1
GET /api/buckets/list

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": [
5
    { "id": 1, "name": "默认存储", "type": "default" },
6
    { "id": 2, "name": "R2", "type": "r2" }
7
  ]
8
}

24. 获取全部存储桶#

返回存储桶详情（含容量、用量、配置等）。

1
GET /api/buckets

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": [
5
    {
6
      "id": 1,
7
      "name": "默认存储",
8
      "type": "default",
9
      "capacity": 0,
10
      "config": { "storagePath": "/uploads" },
11
      "usage": 274794356736,
12
      "usage_readable": "256.78 GB",
13
      "total_readable": "1.00 TB",
14
      "usage_percent": 24.98,
15
      "usage_free": "771.22 GB"
16
    }
17
  ]
18
}

25. 新增存储桶#

1
POST /api/buckets

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "name": "测试存储",
3
  "type": "webdav",
4
  "capacity": 100,
5
  "webdav_url": "https://dav.example.com",
6
  "webdav_user": "user@example.com",
7
  "webdav_pass": "password"
8
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
name	text	存储桶名称（必填）
type	text	存储类型：s3 / r2 / ftp / webdav / telegram（必填）
capacity	int	存储桶容量（单位 GB，0 表示不限制；Telegram 类型可忽略）

各存储类型的配置字段（与上述参数一起放入请求体）：

参数	类型	说明
s3_endpoint	text	S3 服务地址
s3_access_key	text	S3 访问密钥
s3_secret_key	text	S3 密钥
s3_bucket	text	S3 存储桶名称

参数	类型	说明
r2_endpoint	text	R2 服务地址
r2_access_key	text	R2 访问密钥
r2_secret_key	text	R2 密钥
r2_bucket	text	R2 存储桶名称

FTP

参数	类型	说明
ftp_host	text	FTP 服务地址
ftp_user	text	FTP 用户名
ftp_pass	text	FTP 密码
ftp_port	text	FTP 端口

WebDAV

参数	类型	说明
webdav_url	text	WebDAV 服务地址
webdav_user	text	WebDAV 用户名
webdav_pass	text	WebDAV 密码

Telegram

参数	类型	说明
tg_bot_token	text	Telegram Bot Token
tg_receivers	text	Telegram Chat ID

返回示例

1
{
2
  "code": 200,
3
  "message": "添加成功",
4
  "data": {
5
    "id": 3,
6
    "name": "测试存储",
7
    "type": "webdav",
8
    "capacity": 119185342464,
9
    "config": {
10
      "webdav_url": "https://dav.example.com",
11
      "webdav_user": "user@example.com",
12
      "webdav_pass": "password"
13
    },
14
    "usage": 0
15
  }
16
}

26. 更新存储桶#

1
POST /api/buckets/update/:id

认证：需要

请求数据类型：application/json

请求体与参数：同「新增存储桶」——name、type（必须与添加时一致）、capacity 及各存储类型的配置字段；id 为路径参数。

注意：默认存储桶（ID=1）不可编辑；Telegram 类型可忽略 capacity。

返回示例

1
{
2
  "code": 200,
3
  "message": "更新成功",
4
  "data": null
5
}

27. 删除存储桶#

仅移除该存储源上的副本，其它存储源副本与主记录保留。

1
DELETE /api/buckets/:id

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	存储桶 ID

返回示例

1
{
2
  "code": 200,
3
  "message": "删除成功",
4
  "data": null
5
}

28. 启用/停用存储桶#

1
PUT /api/buckets/:id/enabled

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "enabled": false
3
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
id	int	存储桶 ID
enabled	bool	true 启用 / false 停用

注意：本机默认存储桶（ID=1）用于访问回退，不能停用。

返回示例

1
{
2
  "code": 200,
3
  "message": "存储源已临时停用",
4
  "data": { "id": 2, "enabled": false, "disabled": true }
5
}

29. 测试存储桶连接#

1
POST /api/buckets/test

认证：需要

请求数据类型：application/json

请求体：同「新增存储桶」的各存储类型配置字段（如 s3_endpoint、webdav_url 等）。

返回示例

1
{
2
  "code": 200,
3
  "message": "连接测试成功",
4
  "data": { "success": true }
5
}

七、统计（需要 Token）#

30. 仪表板统计#

1
GET /api/stats/dashboard

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例（已省略部分列表项）

1
{
2
  "code": 200,
3
  "message": "获取统计数据成功",
4
  "data": {
5
    "total_images": 26,
6
    "total_size": 920903,
7
    "today_uploads": 0,
8
    "month_uploads": 0,
9
    "recent_images": [
10
      {
11
        "id": 34,
12
        "url": "/uploads/2026/01/188f107f0b67c180175.webp",
13
        "thumbnail": "",
14
        "filename": "188f107f0b67c180175.webp",
15
        "file_size": 117818,
16
        "mimeType": "image/webp",
17
        "width": 640,
18
        "height": 640,
19
        "storage": "default",
20
        "bucket_id": 1,
21
        "user_id": 1,
22
        "md5": "d524973a0133f423b908f311d7bc089a",
23
        "uuid": "admin",
24
        "created_at": "2026-01-29T09:48:36.4202471+08:00"
25
      }
26
    ],
27
    "upload_trend": [{ "date": "2026-03-01", "count": 0 }],
28
    "format_stats": [
29
      { "format": "image/jpeg", "count": 1, "size": 61868 },
30
      { "format": "image/webp", "count": 24, "size": 856774 }
31
    ],
32
    "size_distribution": [
33
      { "range": "< 100KB", "count": 20 },
34
      { "range": "100KB - 500KB", "count": 6 }
35
    ]
36
  }
37
}

31. 图片统计#

1
GET /api/stats/images

认证：需要

参数

参数	类型	说明
Authorization	text	请求头 Bearer token

返回示例

1
{
2
  "code": 200,
3
  "message": "获取图片统计成功",
4
  "data": [
5
    { "date": "2025-12", "count": 2 },
6
    { "date": "2026-01", "count": 24 },
7
    { "date": "2026-02", "count": 0 }
8
  ]
9
}

八、系统设置（需要 Token）#

32. 获取系统设置#

1
POST /api/settings/get

该接口使用 auth.Any 注册，GET 同样可用。

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "keys": []
3
}

keys 为空时返回全部设置；也可以传入指定的键数组进行筛选。

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "id": 1,
6
    "compress_image": false,
7
    "save_webp": true,
8
    "thumbnail": false,
9
    "tourist": true,
10
    "tg_notice": false,
11
    "pow_verify": false,
12
    "verify_method": "cappow",
13
    "turnstile_site_key": "",
14
    "cappow_difficulty": 4,
15
    "start_api": false,
16
    "api_token": "",
17
    "save_original_name": false,
18
    "default_storage": 1,
19
    "watermark_enable": false,
20
    "watermark_text": "初春图床",
21
    "watermark_pos": "bottom-right",
22
    "watermark_size": 10,
23
    "watermark_color": "#000000",
24
    "watermark_opac": 0.5,
25
    "referer_white_enable": false,
26
    "referer_white_list": "",
27
    "seo_title": "初春图床",
28
    "seo_description": "初春图床，一个免费、稳定、高效的图床服务",
29
    "seo_keywords": "初春网络,雾创岛,初春图床,图床,免费,稳定,高效",
30
    "seo_icp": "",
31
    "public_security": "",
32
    "seo_icon": ""
33
  }
34
}

33. 更新系统设置#

1
POST /api/settings/update

认证：需要

请求数据类型：application/json

请求体

1
{
2
  "key": "tourist",
3
  "value": true
4
}

参数

参数	类型	说明
Authorization	text	请求头 Bearer token
key	string	配置项名称（参考「获取系统设置」返回的键）
value	string	配置项值

返回示例

1
{
2
  "code": 200,
3
  "message": "更新成功",
4
  "data": null
5
}

34. 随机图配置#

1
GET /api/settings/randomGraph

1
POST /api/settings/randomGraph

认证：需要

GET 返回当前随机图范围：

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "user_ids": [1, 2],
6
    "tag_ids": []
7
  }
8
}

POST 设置随机图范围，请求体：

1
{
2
  "user_ids": [1, 2],
3
  "tag_ids": [1]
4
}

返回示例

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": null
5
}

九、其他#

35. 图片外链水印参数#

在图片外链 URL 上附加查询参数，即可对该次访问动态添加水印。

1
GET /uploads/xxxx/xx/xxxxxxxxxxxxxx.xxx

认证：无需

参数

参数	类型	说明
watermark	bool	是否开启水印
wm_text	string	水印文字
wm_pos	string	水印位置：top-left / top-right / bottom-left / bottom-right / center
wm_size	float	水印大小
wm_dynamic	bool	是否动态水印
wm_ratio	int	水印动态比例
wm_min_size	int	水印最小尺寸
wm_max_size	int	水印最大尺寸
wm_color	string	水印颜色（16 进制）
wm_opacity	float	水印透明度
wm_font	string	字体文件路径（建议不要加上，防止报错）

写在后面#

以上文档可能存在一些错误，如果发现请及时联系我进行修改，谢谢！