初春图床API文档#

项目地址#

API列表#

TIP
注意，以下返回json为统一返回格式

错误返回示例：

1
{
2
  "code": 4xx-5xx,
3
  "message": "error message",
4
  "data": null
5
}

成功返回示例：

1
{
2
  "code": 200,
3
  "message": "success message",
4
  "data": [
5
    "data json..."
6
  ]
7
}

TIP

随机图

1
/api/images/random

token认证： 否

参数	类型	说明
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
}

TIP

登录设置

1
/api/settings/login

token认证： 否

参数	类型	说明

返回示例：

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "pow_verify": false,
6
    "tourist": true
7
  }
8
}

TIP

SEO设置

1
/api/settings/seo

token认证： 否

参数	类型	说明

返回示例：

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

WARNING
以下所有接口都需要token认证，获取方式在后台->系统设置->API Token中生成获取（支持自定义），使用时必须开启“启用API”选项

TIP

用户信息

1
/api/user/status

token认证： 是

参数	类型	说明
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
}

TIP

获取上传配置

1
/api/uploadConfig

token认证： 是

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

返回示例：

1
{
2
  "code": 200,
3
  "message": "ok",
4
  "data": {
5
    "buckets": [
6
      {
7
        "id": 1,
8
        "name": "默认存储",
9
        "type": "default"
10
      },
11
      {
12
        "id": 2,
13
        "name": "R2",
14
        "type": "r2"
15
      }
16
    ],
17
    "default_bucket": 1,
18
    "tags": [
19
      {
20
        "id": 1,
21
        "name": "TG"
22
      }
23
    ]
24
  }
25
}

TIP

获取标签

1
/api/tags

token认证： 是

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

返回示例：

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

TIP

删除标签

1
/api/tag/:id

token认证： 是

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

返回示例：

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

TIP

添加标签

1
/api/tag

请求数据类型： application/json token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
name	text	标签名称

返回示例：

1
{
2
    "code":200,
3
    "message":"ok",
4
    "data": {
5
        "id":2,
6
        "name":"1111"
7
    }
8
}

TIP

存储桶列表

1
/api/buckets/list

token认证： 是

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

返回示例：

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

TIP

全部存储桶

1
/api/buckets

token认证： 是

参数	类型	说明
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": {
11
                "storagePath": "/uploads"
12
            },
13
            "usage": 274794356736,
14
            "usage_readable": "256.78 GB",
15
            "total_readable": "1.00 TB",
16
            "usage_percent": 24.98,
17
            "usage_free": "771.22 GB"
18
        }
19
    ]
20
}

TIP

新增存储桶

1
/api/buckets

请求数据类型： application/json token认证： 是

参数	类型	说明
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	int	FTP用户名
ftp_pass	text	FTP密码
ftp_port	text	FTP端口

WebDav

参数	类型	说明
webdav_url	text	WebDav服务地址
webdav_user	int	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_pass": "111111111111",
11
            "webdav_url": "https://p.cv0.cn/dav",
12
            "webdav_user": "one@cvmail.cn"
13
        },
14
        "usage": 0
15
    }
16
}

TIP

删除存储桶

1
/api/buckets/:id

token认证： 是

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

返回示例：

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

TIP

更新存储桶

1
/api/buckets/:id

请求数据类型： application/json token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
id	int	存储桶ID
name	text	存储桶名称
type	text	存储桶类型（必须为添加时的存储类型）
capacity	int	存储桶容量（单位为GB，0表示不限制，Telegram类型可忽略）

对应存储配置，添加至上方请求体中

NOTE
请参考上一个新增存储桶

TIP

数据统计

1
/api/stats/dashboard

token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
返回示例：

1
{
2
    "code": 200,
3
    "message": "获取统计数据成功",
4
    "success": true,
5
    "data": {
6
        "total_images": 26,
7
        "total_size": 920903,
8
        "today_uploads": 0,
9
        "month_uploads": 0,
10
        "recent_images": [
11
            {
12
                "id": 34,
13
                "url": "/uploads/2026/01/188f107f0b67c180175.webp",
14
                "thumbnail": "",
15
                "filename": "188f107f0b67c180175.webp",
16
                "file_size": 117818,
17
                "mimeType": "image/webp",
18
                "width": 640,
19
                "height": 640,
20
                "storage": "default",
21
                "bucket_id": 1,
22
                "user_id": 1,
23
                "md5": "d524973a0133f423b908f311d7bc089a",
24
                "uuid": "admin",
25
                "created_at": "2026-01-29T09:48:36.4202471+08:00"
26
            },
27
            {
28
                "id": 33,
29
                "url": "/uploads/2026/01/188cac0b77f4c530867.webp",
30
                "thumbnail": "",
31
                "filename": "188cac0b77f4c530867.webp",
32
                "file_size": 117818,
33
                "mimeType": "image/webp",
34
                "width": 640,
35
                "height": 640,
36
                "storage": "r2",
37
                "bucket_id": 2,
38
                "user_id": 1,
39
                "md5": "1d0e90d59b3c1666340edb71ac56f8d0",
40
                "uuid": "admin",
41
                "created_at": "2026-01-21T14:45:20.0381164+08:00"
42
            },
43
            {
44
                "id": 32,
45
                "url": "/uploads/2026/01/1889534a80182ddc297.webp",
46
                "thumbnail": "",
47
                "filename": "1889534a80182ddc297.webp",
48
                "file_size": 117818,
49
                "mimeType": "image/webp",
50
                "width": 640,
51
                "height": 640,
52
                "storage": "default",
53
                "bucket_id": 1,
54
                "user_id": 2873846347613367382,
55
                "md5": "ab34b8d2a98f7f9c6cab0ed633100790",
56
                "uuid": "35b3fcf8-cbbe-46db-88c0-b369da0c7213",
57
                "created_at": "2026-01-10T17:05:08.1640839+08:00"
58
            },
59
            {
60
                "id": 31,
61
                "url": "/uploads/2026/01/1888f2ff17b11a34238.webp",
62
                "thumbnail": "",
63
                "filename": "1888f2ff17b11a34238.webp",
64
                "file_size": 117818,
65
                "mimeType": "image/webp",
66
                "width": 640,
67
                "height": 640,
68
                "storage": "default",
69
                "bucket_id": 1,
70
                "user_id": 1,
71
                "md5": "f7e0178ed45b0cd97c4d2967fe02bab7",
72
                "uuid": "admin",
73
                "created_at": "2026-01-09T11:40:31.1720163+08:00"
74
            },
75
            {
76
                "id": 30,
77
                "url": "/uploads/2026/01/1888107f117d54ec498.svg",
78
                "thumbnail": "",
79
                "filename": "1888107f117d54ec498.svg",
80
                "file_size": 2261,
81
                "mimeType": "image/svg+xml",
82
                "width": 0,
83
                "height": 0,
84
                "storage": "default",
85
                "bucket_id": 1,
86
                "user_id": 1,
87
                "md5": "34d782dc4a2194c3e3fd82478a2e5aaf",
88
                "uuid": "admin",
89
                "created_at": "2026-01-06T14:29:51.6853567+08:00"
90
            },
91
            {
92
                "id": 29,
93
                "url": "/uploads/2026/01/wps624.webp",
94
                "thumbnail": "",
95
                "filename": "wps624.webp",
96
                "file_size": 5084,
97
                "mimeType": "image/webp",
98
                "width": 480,
99
                "height": 300,
100
                "storage": "default",
101
                "bucket_id": 1,
102
                "user_id": 1,
103
                "md5": "42e425422e4d29803d1ec5722a647a47",
104
                "uuid": "admin",
105
                "created_at": "2026-01-04T11:37:05.908212+08:00"
106
            },
107
            {
108
                "id": 28,
109
                "url": "/uploads/2026/01/tuba24.webp",
110
                "thumbnail": "",
111
                "filename": "tuba24.webp",
112
                "file_size": 5480,
113
                "mimeType": "image/webp",
114
                "width": 480,
115
                "height": 300,
116
                "storage": "default",
117
                "bucket_id": 1,
118
                "user_id": 1,
119
                "md5": "6851f0f6cb8014ced05b6ee5a6a46107",
120
                "uuid": "admin",
121
                "created_at": "2026-01-04T11:37:00.293054+08:00"
122
            },
123
            {
124
                "id": 27,
125
                "url": "/uploads/2026/01/ip.webp",
126
                "thumbnail": "",
127
                "filename": "ip.webp",
128
                "file_size": 6832,
129
                "mimeType": "image/webp",
130
                "width": 480,
131
                "height": 300,
132
                "storage": "default",
133
                "bucket_id": 1,
134
                "user_id": 1,
135
                "md5": "9c33c7b55e97a329e50014f6bbd43f8e",
136
                "uuid": "admin",
137
                "created_at": "2026-01-04T11:26:14.3958124+08:00"
138
            },
139
            {
140
                "id": 26,
141
                "url": "/uploads/2026/01/ip 拷贝.webp",
142
                "thumbnail": "",
143
                "filename": "ip 拷贝.webp",
144
                "file_size": 6548,
145
                "mimeType": "image/webp",
146
                "width": 480,
147
                "height": 300,
148
                "storage": "default",
149
                "bucket_id": 1,
150
                "user_id": 1,
151
                "md5": "e1227a1d993f9ec801792caa651f063f",
152
                "uuid": "admin",
153
                "created_at": "2026-01-04T11:26:14.3576183+08:00"
154
            },
155
            {
156
                "id": 25,
157
                "url": "/uploads/2026/01/cha.webp",
158
                "thumbnail": "",
159
                "filename": "cha.webp",
160
                "file_size": 5066,
161
                "mimeType": "image/webp",
162
                "width": 480,
163
                "height": 300,
164
                "storage": "default",
165
                "bucket_id": 1,
166
                "user_id": 1,
167
                "md5": "bdd10397ad35e332b791ded2cc0fc263",
168
                "uuid": "admin",
169
                "created_at": "2026-01-04T11:26:14.3241777+08:00"
170
            }
171
        ],
172
        "upload_trend": [
173
            {
174
                "date": "2026-02-25",
175
                "count": 0
176
            },
177
            {
178
                "date": "2026-02-26",
179
                "count": 0
180
            },
181
            {
182
                "date": "2026-02-27",
183
                "count": 0
184
            },
185
            {
186
                "date": "2026-02-28",
187
                "count": 0
188
            },
189
            {
190
                "date": "2026-03-01",
191
                "count": 0
192
            },
193
            {
194
                "date": "2026-03-02",
195
                "count": 0
196
            },
197
            {
198
                "date": "2026-03-03",
199
                "count": 0
200
            }
201
        ],
202
        "format_stats": [
203
            {
204
                "format": "image/jpeg",
205
                "count": 1,
206
                "size": 61868
207
            },
208
            {
209
                "format": "image/svg+xml",
210
                "count": 1,
211
                "size": 2261
212
            },
213
            {
214
                "format": "image/webp",
215
                "count": 24,
216
                "size": 856774
217
            }
218
        ],
219
        "size_distribution": [
220
            {
221
                "range": "\u003c 100KB",
222
                "count": 20
223
            },
224
            {
225
                "range": "100KB - 500KB",
226
                "count": 6
227
            },
228
            {
229
                "range": "500KB - 1MB",
230
                "count": 0
231
            },
232
            {
233
                "range": "1MB - 5MB",
234
                "count": 0
235
            },
236
            {
237
                "range": "5MB - 10MB",
238
                "count": 0
239
            },
240
            {
241
                "range": "\u003e 10MB",
242
                "count": 0
243
            }
244
        ]
245
    }
246
}

TIP

每日上传统计

1
/api/stats/images

token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
返回示例

1
{
2
  "code": 200,
3
  "message": "获取图片统计成功",
4
  "success": true,
5
  "data": [
6
    {
7
      "date": "2025-04",
8
      "count": 0
9
    },
10
    {
11
      "date": "2025-05",
12
      "count": 0
13
    },
14
    {
15
      "date": "2025-06",
16
      "count": 0
17
    },
18
    {
19
      "date": "2025-07",
20
      "count": 0
21
    },
22
    {
23
      "date": "2025-08",
24
      "count": 0
25
    },
26
    {
27
      "date": "2025-09",
28
      "count": 0
29
    },
30
    {
31
      "date": "2025-10",
32
      "count": 0
33
    },
34
    {
35
      "date": "2025-11",
36
      "count": 0
37
    },
38
    {
39
      "date": "2025-12",
40
      "count": 2
41
    },
42
    {
43
      "date": "2026-01",
44
      "count": 24
45
    },
46
    {
47
      "date": "2026-02",
48
      "count": 0
49
    },
50
    {
51
      "date": "2026-03",
52
      "count": 0
53
    }
54
  ]
55
}

TIP

图片上传接口

1
/api/upload/images

token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
file	file	文件
bucket_id	int	存储桶ID

返回示例

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
}

TIP

图片批量上传接口

1
/api/upload/images

token认证： 是

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

返回示例

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
}

TIP

图片删除接口

1
/api/images/:id

token认证： 是

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

返回示例

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

TIP

获取图片列表

1
/api/images

token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
page	int	页码
limit	int	每页数量
sort_order	desc/asc	排序方式
order_by	created_at	排序字段
role	admin/guest	角色
tags	int	标签ID（支持多条件，例如：0,1,2,3）
bucket_id	int	存储桶ID

返回示例

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": [
22
                    {
23
                        "id": 0,
24
                        "name": "默认"
25
                    }
26
                ]
27
            }
28
        ],
29
        "limit": 20,
30
        "page": 1,
31
        "total": 1,
32
        "total_pages": 1
33
    }
34
}

TIP

获取图片详情

1
/api/images/:id

token认证： 是

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

返回示例

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

TIP

添加图片标签

1
/api/images/tags

token认证： 是

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

返回示例

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

TIP

删除图片标签

1
/api/images/tags

token认证： 是

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

返回示例

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

TIP

批量删除图片标签

1
/api/images/tags

token认证： 是

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

返回示例

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

TIP

批量添加图片标签

1
/api/images/tags

token认证： 是

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

返回示例

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

TIP

获取系统设置

1
/settings/get

token认证： 是

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

返回示例

1
{
2
    "code": 200,
3
    "message": "ok",
4
    "data": {
5
        "id": 1,
6
        "original_image": false,
7
        "save_webp": true,
8
        "thumbnail": false,
9
        "tourist": true,
10
        "tg_notice": false,
11
        "pow_verify": false,
12
        "tg_bot_token": "",
13
        "tg_receivers": "",
14
        "tg_notice_text": "",
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
}

TIP

更新设置

1
/api/settings/update

token认证： 是

参数	类型	说明
Authorization	text	请求头Bearer token
key	string	配置项名称
value	string	配置项值

NOTE
key值请参考上方返回示例

返回示例

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

TIP

图片外链自定义水印参数

1
/uploads/xxxx/xx/xxxxxxxxxxxxxx.xxx

token认证： 否

参数	类型	说明
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	字体文件路径（建议不要加上，防止报错）

TIP

通过URL上传图片

1
/api/images/url

token认证： 是

参数	类型	说明
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
}

写在后面#

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