API REFERENCE · V1

云图 API

快速调用图片资源，按分类检索可用内容，并获取实时服务状态。

身份鉴权

接口支持匿名调用。使用 API Key 时，请在管理控制台创建密钥后，将明文密钥放入请求头；密钥仅在创建后展示一次。

X-API-Key: your_api_key

GET

`/api/images/random`

随机返回一张来自已启用分类的有效图片。

参数	类型	说明
`category`	string	可选，指定分类 slug。
`redirect`	boolean	可选，是否 302 跳转至图片地址。

{
  "success": true,
  "data": {
    "id": 1,
    "title": "示例图片",
    "url": "https://example.com/storage/images/demo.jpg",
    "category": "wallpaper",
    "mime_type": "image/jpeg"
  }
}

GET

`/api/categories`

返回所有已启用分类，以及每个分类中可供调用的图片数量。

GET

`/api/health`

返回服务运行状态与当前服务器时间，可用于监控和健康检查。

错误码

状态码	说明
401	提供的 API Key 无效或已被停用。
404	没有符合条件的可用图片。
429	当前请求频率超过服务限额。