接口文档

随机图片接口

全部为 GET 请求。默认 302 跳转到图片，带 format=json 返回结构化数据。

接口地址

统一入口

https://hanami.lolin.cn/api.php?act=rand

参数

全部可选

参数	类型	默认	说明
`act`	string	rand	rand 取图 / stats 统计 / health 健康检查
`count`	int	1	返回数量 1–50，大于 1 时默认 JSON
`format`	string	自动	redirect / json / text
`tag`	string	空	按标签筛选，留空为全部
`key`	string	空	后台开启鉴权后必填
`cdn`	0/1	跟随后台	是否拼接 CDN 加速域名
`proxy`	0/1	0	服务器中转输出图片，完全隐藏源地址（需后台开启）

调用示例

curl

# 302 跳转到一张随机图
curl -L "https://hanami.lolin.cn/api.php?act=rand"

# JSON 单张
curl "https://hanami.lolin.cn/api.php?act=rand&format=json"

# 一次 10 张
curl "https://hanami.lolin.cn/api.php?act=rand&count=10"

# 指定标签 + 鉴权
curl "https://hanami.lolin.cn/api.php?act=rand&count=5&tag=sakura&key=YOUR_KEY"

# 纯文本，每行一条
curl "https://hanami.lolin.cn/api.php?act=rand&count=20&format=text"

# 统计
curl "https://hanami.lolin.cn/api.php?act=stats"

返回结构

format=json

{
  "code": 0,
  "msg": "ok",
  "count": 2,
  "data": [
    { "id": 14, "url": "https://img.example.com/a.jpg", "tag": "sakura", "title": "" },
    { "id": 22, "url": "https://img.example.com/b.jpg", "tag": "scenery", "title": "" }
  ]
}

状态码

业务 code

code	HTTP	含义
`0`	200	成功
`4010`	401	Key 缺失 / 无效 / 配额用尽
`4041`	404	没有可用图片
`4290`	429	触发频率限制，响应头带 Retry-After
`5030`	503	维护模式

接入建议

性能与稳定

直接引用跳转地址
前端 img 的 src 写接口地址即可，浏览器会自动跟随 302。

批量场景用 JSON
一次拿多条链接，减少请求数；配合 count 上限 50。