CZL 图床 API 文档

HTML 文档: https://img.czl.net/api-docs.html
Markdown 文档: https://img.czl.net/api-docs.md
旧地址兼容: https://img.czl.net/page/api-docs.html
API Base URL: https://img.czl.net/api/v1

接入说明

所有接口都返回 JSON。
当前版本接口采用「Bearer Token」的方式验证授权，从个人中心获取 Token 后，通过 Authorization 请求头传递，例如：Authorization: Bearer 1|1bJbwlqBfnggmOMEZqXT5XusaIwqiZjCDs7r1Ob5。
上传接口使用 multipart/form-data，文件字段名固定为 file。
POST /upload 在未携带 Authorization 时会按游客上传处理；是否允许游客上传取决于后台配置。
GET /strategies 在未登录时会返回游客组可用策略；登录后返回当前用户组可用策略。
文档中接口的请求参数，使用红色「*」符号或"必填=是"标注，则表示为必传项。

统一响应结构

{
  "status": true,
  "message": "success",
  "data": {}
}

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据，空数据时返回空对象

公共请求 headers

字段	类型	必填	说明
`Authorization`	String	否	授权 Token，例如：`Bearer 1
`Accept`	String	是	必须设置为 `application/json`

公共响应 headers

字段	类型	说明
`X-RateLimit-Limit`	Integer	当前客户端一分钟内请求配额
`X-RateLimit-Remaining`	Integer	当前客户端剩余请求配额

限流说明

所有 /api/v1/* 接口统一限流 180 次/分钟，按登录用户（或未登录时按 IP）计数，超出返回 429。
上传接口 (POST /upload) 额外受角色组「上传频率限制」约束（分钟/小时/天/周/月各档独立限额，登录用户看个人中心，游客看默认组配置），与上面的 180 次/分钟限流分别计算、都可能触发。
批量操作请优先使用批量接口而不是循环调用单条接口，例如删除大量图片用 DELETE /images（一次最多 1000 张）代替循环调用 DELETE /images/{key}，可大幅减少请求次数，避免撞到限流。

响应状态码 HTTP Status Code 说明

状态码	说明
`200`	请求成功
`401`	未登录或授权失败
`403`	管理员关闭了接口功能或没有该接口权限
`429`	超出请求配额，请求受限
`500`	服务端出现异常

快速示例

获取当前用户资料

curl --request GET "https://img.czl.net/api/v1/profile" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_TOKEN"

上传图片

curl --request POST "https://img.czl.net/api/v1/upload" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --form "file=@/path/to/demo.png" \
  --form "strategy_id=1" \
  --form "permission=0"

用户相关

`GET /profile`

获取当前登录用户资料。

认证要求: 必须登录
请求参数: 无

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.username`	String	用户名
`data.name`	String	昵称
`data.avatar`	String	头像地址
`data.email`	String	邮箱地址
`data.capacity`	Float	总容量
`data.size`	Float	已使用容量
`data.url`	String	个人主页地址
`data.image_num`	Integer	图片数量
`data.album_num`	Integer	相册数量
`data.registered_ip`	String	注册 IP

响应示例:

{
  "status": true,
  "message": "success",
  "data": {
    "username": "demo",
    "name": "示例用户",
    "avatar": "https://img.czl.net/api/v1/../avatar/demo.png",
    "email": "[email protected]",
    "capacity": 1048576.0,
    "size": 20480.5,
    "url": "https://img.czl.net/api/v1/../demo",
    "image_num": 128,
    "album_num": 6,
    "registered_ip": "203.0.113.10"
  }
}

策略相关

`GET /strategies`

获取当前用户组可用的储存策略列表。

认证要求: 可匿名；未登录时返回游客组可用策略，登录时按当前用户组返回
请求体类型: 无

请求参数(Query):

字段	类型	必填	说明
`q`	String	否	筛选关键字

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.strategies`	Object[]	策略数据
`data.strategies[].id`	Integer	策略 ID
`data.strategies[].name`	String	策略名称

响应示例:

{
  "status": true,
  "message": "success",
  "data": {
    "strategies": [
      { "id": 1, "name": "本地存储" },
      { "id": 2, "name": "MinIO 对象存储" }
    ]
  }
}

图片相关

`POST /images/tokens`

生成临时上传 Token。

认证要求: 必须登录
请求体类型: application/json 或表单均可

请求参数(Body):

字段	类型	必填	说明
`num`	Integer	是	生成数量，最大 100
`seconds`	Integer	是	有效期(秒)，最大 `2626560`（一个月）

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.tokens`	Object[]	临时 Token 列表
`data.tokens[].token`	String	token
`data.tokens[].expired_at`	String	到期时间，格式 `yyyy-MM-dd HH:mm:ss`

请求示例:

{
  "num": 2,
  "seconds": 3600
}

响应示例:

{
  "status": true,
  "message": "success",
  "data": {
    "tokens": [
      { "token": "9f8c1d2e3a4b5c6d7e8f9012", "expired_at": "2026-06-22 15:30:00" },
      { "token": "0a1b2c3d4e5f60718293a4b5", "expired_at": "2026-06-22 15:30:00" }
    ]
  }
}

`POST /upload`

上传图片。

认证要求: 可匿名；登录后可使用用户能力、相册、默认策略等
请求体类型: multipart/form-data

Headers:

字段	类型	必填	说明
`Content-Type`	String	是	需要设置为 `multipart/form-data`

请求参数(Body):

字段	类型	必填	说明
`file`	File	是	图片文件
`token`	String	否	临时上传 Token；适合无需长期 Bearer Token 的上传场景
`permission`	Integer	否	图片广场展示状态，`1`=展示到图片广场，`0`=不展示到图片广场；不影响原图 URL 访问
`image_id`	Integer	否	重新上传并覆盖当前用户已有图片时使用
`strategy_id`	Integer	否	储存策略 ID
`album_id`	Integer	否	相册 ID
`expired_seconds`	Integer	否	自动删除秒数，最大 `15759360`（约 6 个月）
`expired_at`	String	否	图片过期时间，格式 `yyyy-MM-dd HH:mm:ss`

补充说明:

当用户组配置了固定过期时间时，自定义 expired_seconds / expired_at 会被系统策略覆盖。
自定义删除时间最长不能超过 1 年。
如果不传 strategy_id，系统会优先使用用户默认策略，否则回退到当前组的第一个可用策略。

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.key`	String	图片唯一密钥
`data.name`	String	图片名称
`data.pathname`	String	图片路径名
`data.origin_name`	String	图片原始名
`data.size`	Float	图片大小，单位 KB
`data.mimetype`	String	图片类型
`data.extension`	String	图片拓展名
`data.md5`	String	图片 md5 值
`data.sha1`	String	图片 sha1 值
`data.links`	Object	链接
`data.links.url`	String	图片访问 url
`data.links.html`	String	HTML 嵌入代码
`data.links.bbcode`	String	BBCode
`data.links.markdown`	String	Markdown 图片语法
`data.links.markdown_with_link`	String	带跳转链接的 Markdown
`data.links.thumbnail_url`	String	缩略图 url

响应示例:

{
  "status": true,
  "message": "success",
  "data": {
    "key": "aB3xY7",
    "name": "aB3xY7.png",
    "pathname": "2026/06/22/aB3xY7.png",
    "origin_name": "demo.png",
    "size": 256.42,
    "mimetype": "image/png",
    "extension": "png",
    "md5": "9e107d9d372bb6826bd81d3542a419d6",
    "sha1": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
    "links": {
      "url": "https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png",
      "html": "<img src=\"https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png\" alt=\"demo.png\">",
      "bbcode": "[img]https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png[/img]",
      "markdown": "![demo.png](https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png)",
      "markdown_with_link": "[![demo.png](https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png)](https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png)",
      "thumbnail_url": "https://img.czl.net/api/v1/../thumb/2026/06/22/aB3xY7.png"
    }
  }
}

`GET /images`

分页获取当前用户的图片列表。

认证要求: 必须登录

请求参数(Query):

字段	类型	必填	说明
`page`	Integer	否	页码；默认分页模式使用
`pagination`	String	否	分页模式；传 `cursor` 时启用游标分页
`cursor`	String	否	游标；`pagination=cursor` 时继续请求下一页使用
`order`	String	否	排序方式：`newest`=最新，`earliest`=最早，`utmost`=最大，`least`=最小，`like-desc`=点赞最多，`like-asc`=点赞最少，`view-desc`=浏览最多，`view-asc`=浏览最少，`origin-name-asc`=原始名升序，`origin-name-desc`=原始名降序
`permission`	String	否	图片广场展示筛选：`public`=展示到图片广场，`private`=不展示到图片广场
`album_id`	Integer	否	相册 ID
`q`	String	否	筛选关键字

分页模式:

页码分页: 默认模式，返回 current_page、last_page、total 等字段，支持按页码跳转。
游标分页: 客户端显式传 pagination=cursor 时启用，返回 next_cursor、prev_cursor、next_page_url、prev_page_url 等字段，不返回 last_page 与 total，客户端继续请求下一页时传入 pagination=cursor&cursor=next_cursor。
当请求显式包含 page，或排序不适合游标分页时，接口继续使用页码分页。

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.current_page`	Integer	当前所在页页码
`data.last_page`	Integer	最后一页页码
`data.per_page`	Integer	每页展示数据数量
`data.total`	Integer	图片总数量
`data.next_cursor`	String	null
`data.prev_cursor`	String	null
`data.data`	Object[]	图片列表
`data.data[].key`	String	图片唯一密钥
`data.data[].name`	String	图片名称
`data.data[].origin_name`	String	图片原始名称
`data.data[].pathname`	String	图片路径名
`data.data[].size`	Float	图片大小，单位 KB
`data.data[].mimetype`	String	图片类型
`data.data[].extension`	String	图片拓展名
`data.data[].width`	Integer	图片宽度
`data.data[].height`	Integer	图片高度
`data.data[].md5`	String	图片 md5 值
`data.data[].sha1`	String	图片 sha1 值
`data.data[].human_date`	String	上传时间(友好格式)
`data.data[].date`	String	上传日期，格式 `yyyy-MM-dd HH:mm:ss`
`data.data[].links`	Object	链接，与上传接口返回参数中的 `links` 相同

响应示例:

页码分页:

{
  "status": true,
  "message": "success",
  "data": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 30,
    "total": 128,
    "data": [
      {
        "key": "aB3xY7",
        "name": "aB3xY7.png",
        "origin_name": "demo.png",
        "pathname": "2026/06/22/aB3xY7.png",
        "size": 256.42,
        "mimetype": "image/png",
        "extension": "png",
        "width": 1280,
        "height": 720,
        "md5": "9e107d9d372bb6826bd81d3542a419d6",
        "sha1": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
        "human_date": "3 分钟前",
        "date": "2026-06-22 14:27:00",
        "links": { "url": "https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png" }
      }
    ]
  }
}

游标分页:

{
  "status": true,
  "message": "success",
  "data": {
    "per_page": 40,
    "next_cursor": "eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "next_page_url": "https://img.czl.net/api/v1/images?cursor=eyJpZCI6MTAwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
    "prev_cursor": null,
    "prev_page_url": null,
    "data": [
      {
        "key": "aB3xY7",
        "name": "aB3xY7.png",
        "origin_name": "demo.png",
        "pathname": "2026/06/22/aB3xY7.png",
        "size": 256.42,
        "mimetype": "image/png",
        "extension": "png",
        "width": 1280,
        "height": 720,
        "md5": "9e107d9d372bb6826bd81d3542a419d6",
        "sha1": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
        "human_date": "3 分钟前",
        "date": "2026-06-22 14:27:00",
        "links": { "url": "https://img.czl.net/api/v1/../i/2026/06/22/aB3xY7.png" }
      }
    ]
  }
}

`DELETE /images/{key}`

删除指定图片。

认证要求: 必须登录

请求参数(Params):

字段	类型	必填	说明
`key`	String	是	图片密钥

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据

响应示例:

{
  "status": true,
  "message": "删除成功",
  "data": {}
}

`DELETE /images`

批量删除图片，单次最多 1000 张；需删除更多请分批调用。

认证要求: 必须登录

请求参数(Body JSON):

字段	类型	必填	说明
`keys`	Array<String>	是	图片密钥数组

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.count`	Integer	实际删除的图片数量

响应示例:

{
  "status": true,
  "message": "删除成功",
  "data": {
    "count": 3
  }
}

相册相关

`GET /albums`

分页获取当前用户的相册列表。

认证要求: 必须登录

请求参数(Query):

字段	类型	必填	说明
`page`	Integer	否	页码
`order`	String	否	排序方式：`newest`=最新，`earliest`=最早，`most`=图片最多，`least`=图片最少，`like-desc`=点赞最多，`like-asc`=点赞最少，`view-desc`=浏览最多，`view-asc`=浏览最少
`permission`	String	否	权限筛选：`public`=公开，`private`=私有
`q`	String	否	筛选关键字

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据
`data.current_page`	Integer	当前所在页页码
`data.last_page`	Integer	最后一页页码
`data.per_page`	Integer	每页展示数据数量
`data.total`	Integer	相册总数量
`data.data`	Object[]	相册列表
`data.data[].id`	Integer	相册自增 ID
`data.data[].name`	String	相册名称
`data.data[].intro`	String	相册简介
`data.data[].image_num`	Integer	相册图片数量

响应示例:

{
  "status": true,
  "message": "success",
  "data": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 30,
    "total": 2,
    "data": [
      { "id": 1, "name": "默认相册", "intro": "上传时未指定相册的图片", "image_num": 42 },
      { "id": 2, "name": "壁纸收藏", "intro": "", "image_num": 18 }
    ]
  }
}

`DELETE /albums/{id}`

删除指定相册。

认证要求: 必须登录

请求参数(Params):

字段	类型	必填	说明
`id`	String	是	相册自增 ID

返回参数:

字段	类型	说明
`status`	Boolean	状态，true 或 false
`message`	String	描述信息
`data`	Object	数据

给 AI / 插件作者的建议

优先读取这份 Markdown 文档，而不是解析页面 DOM。
上传接口必须使用 multipart/form-data，并确认文件字段名是 file。
分页接口请按统一响应结构读取 data.data；默认页码分页使用 data.current_page / data.last_page / data.total，显式 pagination=cursor 时使用 data.next_cursor 继续加载。
如果你在做 WordPress、Obsidian、Raycast、n8n、Dify、Coze、浏览器扩展或自定义 SDK，建议先接通 GET /strategies、POST /upload、GET /images 这三条主链路。