星河API星河 API 观测平台

随机图片

GET 需密钥

从本地图片库随机返回一张图片。图片按分类（文件夹）组织，输出统一转 webp（质量默认 80）；默认直接输出图片本体，可切换为 JSON 直出链接或 Base64 返回多张；支持 width / height 参数按指定尺寸缩放（双给为 cover 居中裁剪，单给为等比缩放）。

调用地址

https://api.shurans.cn/api/random-image

调用方式

GET

# 请求头携带密钥
Authorization: Bearer <你的密钥>

请求参数

参数必填示例说明
category 可选 anime 分类名（storage/images/ 下一级子文件夹名）。省略 = 全库随机；分类不存在返回 400；分类存在但暂无图片时自动兜底 default 分类
format 可选 json 输出格式：image 直接输出图片（默认）| json 返回直出链接数组 | base64 返回 mime + Base64 数组（json / base64 支持多张）
count 可选 3 返回张数，1–20，默认 1；仅 format=json / base64 时生效，图片池不足时按实际数量返回
width 可选 300 目标宽度（像素），16–4096；与 height 同时给出 → cover（等比缩放 + 居中裁剪，精确 width×height）；单给 → 等比缩放
height 可选 200 目标高度（像素），16–4096；语义同 width
quality 可选 80 webp 编码质量，1–100，默认 80；显式给出时会忽略「webp 源图原样透传」优化（即强制重编码）

响应示例

{
    "code": 200,
    "message": "ok",
    "data": {
        "category": "anime",
        "count": 2,
        "images": [
            "http://localhost:8080/api/random-image?file=anime%2Fa-01.jpg&width=300",
            "http://localhost:8080/api/random-image?file=anime%2Fb-02.png&width=300"
        ]
    },
    "meta": { "request_id": "7214361835712ec46e74081384fc82be" }
}

响应字段说明

字段说明
data.category 实际取图分类（取首张所在分类，空分类兜底后可能与请求不同；多张时可能跨分类）
data.count 实际返回的张数
data.images format=json 时为直出链接数组（本接口 /api/random-image?file=… 形式，含尺寸参数）；format=base64 时为 [{mime, data}] 数组，data 可直接用于 data URI

© 2026 星河 API