API 文档

返回一张随机图片。可通过参数指定分类和返回格式。

请求参数

参数	类型	必需	默认值	说明
`category`	string	否	-	分类标识(slug)，指定后从该分类及子分类中随机返回
`type`	string	否	`json`	返回类型：`json` 返回结构化数据，`redirect` 302重定向至图片
`size`	string	否	`original`（原图）	取图尺寸：`sm`(320) / `md`(640) / `lg`(1280) / `original`(原图)。传什么就返回什么：`url` 就是该尺寸的直链，响应里其余字段（`width` / `height` / `mime_type` / `file_size`）都描述这一张图。取值非法时返回 `400`（不静默回退，否则调用方会误以为拿到了指定尺寸）；该尺寸尚未生成时按 `请求尺寸 → md → 原图` 回退（绝不返回 404），响应里的 `size` 字段如实回报实际生效的尺寸，回退也能被察觉。图库或所选分类为空时返回 `404` 与 JSON 错误体（`message` 含中文引导，`error` 保持英文机器码）

请求示例

curl -H "X-API-Key: mr_your_api_key_here" "https://your-domain.com/api/v1/random?category=landscape&type=json"

JSON 响应示例

不传 size 时返回原图（与既有调用方一致）：只有 url 一个地址字段。

{
  "success": true,
  "data": {
    "id": 42,
    "url": "https://cdn.example.com/2026/08/abc123def/original.png",
    "size": "original",
    "width": 1920,
    "height": 1080,
    "mime_type": "image/png",
    "file_size": 2048576,
    "category": "landscape"
  }
}

传了 size 就换成那一张 —— url、宽高、格式、字节数全部跟着变：

{
  "success": true,
  "data": {
    "id": 42,
    "url": "https://cdn.example.com/2026/08/abc123def/thumb-sm.webp",
    "size": "sm",
    "width": 320,
    "height": 180,
    "mime_type": "image/webp",
    "file_size": 18432,
    "category": "landscape"
  }
}

缩略图的字节数在生成时实测入库，所以是精确值；更早的图片可能还没记录，此时 file_size 为 null（表示「未知」，不是 0）—— 到后台跑一次「补全缩略图」即可补齐。

缩略图示例

# 只要 URL（JSON），取 320px 缩略图
curl -H "X-API-Key: mr_your_api_key_here" "https://your-domain.com/api/v1/random?size=sm"

# 直接把缩略图当图片用（HTTP 302 跳到缩略图直链）
curl -L -H "X-API-Key: mr_your_api_key_here" "https://your-domain.com/api/v1/random?type=redirect&size=sm"

# 列表页推荐：一次取一批，用 size 指定要哪种尺寸（比逐张调 random 省配额）
curl -H "X-API-Key: mr_your_api_key_here" "https://your-domain.com/api/v1/images?limit=20&size=sm"

返回 URL 的时效性

响应里的 url 是带签名的直链，按存储实例的 signed_ttl 生效（默认 300 秒，云端为预签名、本地为 /files 短时签名）。请勿把返回的 URL 长期存库或嵌到第三方页面 —— 过期后会失效，重新请求本接口即可。需要长期稳定的直链，请给存储实例配置 CDN 域名。

另外：/random 的响应带 Cache-Control: no-store。这不是保守设置而是**功能性要求** —— 该接口的 URL 固定、语义却是「每次换一张」，一旦被缓存，随机性会在缓存期内整体失效。

重定向模式

curl -L -H "X-API-Key: mr_your_api_key_here" "https://your-domain.com/api/v1/random?type=redirect"
# HTTP 302 → 图片直接输出

请求参数

参数	类型	默认值	说明
`page`	int	1	页码
`limit`	int	20	每页数量（最大100）
`category`	string	-	分类过滤

返回完整分类树结构（嵌套JSON），包含所有分类及其子分类。

返回图片总数、分类总数、版本号、当前存储驱动等信息。

{
  "success": true,
  "data": {
    "total_images": 1234,
    "total_categories": 15,
    "version": "2.0.0-beta.13",
    "storage_driver": "local"
  }
}

速率限制

API 使用令牌桶算法实现速率限制，通过响应头返回实时配额信息：

响应头	说明
`X-RateLimit-Limit`	时间窗口内最大请求数
`X-RateLimit-Remaining`	当前窗口剩余请求数
`X-RateLimit-Reset`	窗口重置时间（Unix 时间戳）
`Retry-After`	限流后建议重试等待秒数（仅触发限流时返回）

匿名用户（IP 限流）

60 / 分钟

API Key（默认配额）

60 / 分钟

API Key（可自定义）

∞ 可配置

超限时返回 HTTP 429 状态码，响应体包含 retry_after 字段提示等待时间。