做壁纸站和图库的时候，经常需要一个”随机取一张图”的接口。现成的方案大致分两类：一种只返回外链地址，图片本身不归你管；另一种是遍历目录直接吐出文件，格式和终端适配都得自己在调用侧兜。用久了就干脆自己写一个，也就是现在的 PicFlow API。
它是我自己长期在用的随机图服务，现在跑到 v2.0，纯 PHP，扔进任何支持 PHP 7.4 的空间就能用。
它做的事情
核心只有一个入口：GET /api_v2.php。剩下的都是围绕它的参数。
- 智能格式检测：按浏览器 User-Agent 挑当前支持的最优格式，优先级 AVIF → WebP → JPEG
- 设备自适应：
type=pc取桌面图，type=pe取移动图，auto自动判断 - 两种图源：本地模式读服务器上已经转换好的图片；外链模式从
pc.txt/pe.txt里配置的链接随机取 - 三种返回：JSON 结构体、纯文本地址列表，或者
return=redirect直接 302 到图片 - 系统监控：页面自带面板，能看 PHP 版本、内存占用、访问信息，也提供 JSON 接口
参数不算多，常用的就这几个：count（1–50）、type、img_format、format、return、external。
目录长这样
picflow-api
- index.php系统信息面板
- api_v2.php随机图接口
- pc.txt外链模式：桌面图地址
- pe.txt外链模式：移动图地址
images
- pc原始桌面图
- pe原始移动图
converted
pc
- webp
- jpeg
- avif
pe
- webp
- jpeg
- avif
- API.md完整接口文档
需要说明的是：接口只读 converted/ 里已经转换好的图，原始图放在 images/ 下再跑一次批量转换。这样做的好处是响应时不用现场压图，代价是换图后要记得重新转一遍。
部署
把它跑起来
准备 PHP 环境
PHP 7.4+ 和 GD 扩展即可。1Panel / 宝塔这类面板建站点时选对应的 PHP 版本就能满足。
上传源码
把仓库内容放到站点根目录，然后给
converted/写权限：Terminal window chmod 755 images/ converted/chmod -R 777 converted/配好 Nginx 重写
location / {try_files $uri $uri/ /index.php?$query_string;}Apache 用户用仓库里自带的
.htaccess就行。放图并转换
原始图放进
images/pc和images/pe，没装 Windows 的话用 README_CONVERT 里的说明跑转换脚本，产物进converted/。
调起来是什么样
# 一张自动格式的桌面图（JSON）curl "https://your-domain.com/api_v2.php"
# 五张移动端 WebPcurl "https://your-domain.com/api_v2.php?count=5&type=pe&img_format=webp"
# 直接跳转到图片，适合 <img src="...">curl "https://your-domain.com/api_v2.php?return=redirect"
# 外链模式，从 pc.txt 里取curl "https://your-domain.com/api_v2.php?external=true&count=3"format=text 时只回地址，一行一张，拿来塞进别的程序很省事；做成混合接口也可以——pc.txt 里既能填自己的图，也能填别人的图片 API。
一点设计取舍
- 不做现场转码：转换放在部署阶段，接口只负责随机与输出，服务器压力小
- 不依赖数据库：图片和配置都是文件，备份就是拷目录
- 不做花哨的后台：面板只用于看系统状态和调试，改配置直接改文件
项目是 MIT 协议，完整参数和响应示例都在仓库的 API.md 里。
分享文章
生成精美分享图或复制链接，与更多人分享本文。
继续阅读
最后更新于 ，距今已过 429 天
部分内容可能已过时
评论