参数	类型	默认值	说明
`mode`	string	`auto`	强制指定类型：`auto` / `mobile` / `desktop`
`orientation`	string	`auto`	屏幕方向：`portrait` / `landscape`
`device`	string	`auto`	设备类型：`mobile` / `desktop`
`format`	string	`redirect`	响应格式：`redirect`（302 跳转）/ `json`

示例请求：

# 默认 302 跳转到随机图片
curl https://randbg.smyhub.com/api/random

# 返回 JSON
curl https://randbg.smyhub.com/api/random?format=json
# 响应：
# {
#   "variant": "desktop",
#   "folder": "desketop-image",
#   "filename": "7.webp",
#   "url": "https://randbg.smyhub.com/desketop-image/7.webp",
#   "count": 19
# }

# 强制使用移动端图片
curl https://randbg.smyhub.com/api/random?mode=mobile

# 强制桌面端并返回 JSON
curl https://randbg.smyhub.com/api/random?mode=desktop&format=json

`GET /api/list`

返回各变体的图片清单与统计信息。

curl https://randbg.smyhub.com/api/list

响应示例：

{
  "generated_at": "2026-05-18T11:45:45.514521+00:00",
  "variants": {
    "mobile": {
      "folder": "mobile-image",
      "count": 6,
      "images": ["1.webp", "2.webp", "3.webp", "4.webp", "5.webp", "6.webp"]
    },
    "desktop": {
      "folder": "desketop-image",
      "count": 19,
      "images": ["1.webp", "2.webp", ...]
    }
  }
}

`GET /manifest.json`

静态清单文件，由 build.py 自动生成，记录各变体的目录与文件名列表。

技术栈

层级	技术
Runtime	Cloudflare Workers
静态托管	Cloudflare Workers Static Assets
构建脚本	Python 3 + Pillow
前端	Vanilla HTML / CSS / JS

项目结构

randbg-api/
├── src/
│   ├── worker.js              # Workers 入口路由
│   ├── api/
│   │   ├── random.js          # /api/random 接口逻辑
│   │   └── list.js            # /api/list 接口逻辑
│   └── lib/
│       └── background.js      # 通用工具（清单加载、设备识别、URL 构建）
├── public/
│   ├── index.html             # 演示与文档页面
│   ├── manifest.json          # 图片清单（build.py 生成）
│   ├── _headers               # 静态资源 HTTP 响应头
│   ├── mobile-image/          # 移动端 WebP 图片（构建产物）
│   └── desketop-image/        # 桌面端 WebP 图片（构建产物）
├── mobile-image/              # 原始图片（本地工作目录，不提交到 Git）
├── desketop-image/            # 原始图片（本地工作目录，不提交到 Git）
├── build.py                   # 构建脚本：原图 → WebP + manifest.json
├── wrangler.toml              # Workers 部署配置
├── package.json               # 依赖与脚本
└── README.md                  # 本文档

注意：根目录下的 mobile-image/ 和 desketop-image/ 仅用于本地存放原始素材，不应提交到 GitHub。build.py 会将转换后的编号 WebP 输出到 public/ 目录，只有 public/ 下的内容会被部署。

部署指南

前置条件

1. 克隆项目

git clone https://github.com/shumengya/randbg-api.git
cd randbg-api

2. 安装依赖

npm install

3. 准备图片

将原始图片放入对应目录：

mobile-image/        # 竖屏图片（移动端）
desketop-image/      # 横屏图片（桌面端）

支持格式：.jpg .jpeg .png .bmp .gif .tif .tiff .webp

4. 构建 WebP 与清单

python3 build.py

脚本会自动完成以下工作：

将原图转换为高质量编号 WebP（1.webp 2.webp ...）
生成 public/manifest.json
将转换后的文件输出到 public/ 部署目录

如果 public/ 下已有序号 WebP 且没有原图，脚本会保留现有文件，不会误删。

5. 本地预览

npm run dev

默认在 http://localhost:8787 启动预览。

6. 部署到 Cloudflare

npm run deploy

Wrangler 会将 src/worker.js 打包为 Worker，同时将 public/ 作为静态 Assets 一起发布。

目录约定

public/mobile-image/：竖屏图片（移动端）
public/desketop-image/：横屏图片（桌面端）
- 注意拼写沿用历史目录名，API 内部已兼容
public/manifest.json：构建产物，API 运行时通过内部请求读取该清单

注意事项

原图不上传：根目录下的 mobile-image/ 和 desketop-image/ 仅用于本地构建，已配置 .gitignore 避免误提交。GitHub 仓库中只保留构建后的 public/ 资源。
图片版权：请确保上传的图片拥有合法使用权或来自版权友好的来源。
Worker 体积限制：静态资源通过 Cloudflare Assets 提供，不占用 Worker 脚本 4 MiB 限制，可放心使用大量图片。
缓存策略：public/_headers 已为图片配置了 immutable 长期缓存，为 manifest.json 配置了 5 分钟缓存。如需更新图片，请重新运行 build.py 并部署。

开源协议

本项目基于 MIT License 开源。

贡献

欢迎提交 Issue 和 Pull Request！如果你有任何建议或发现问题，请随时反馈。

Made with ❤️ by shumengya

README.md Unescape Escape

RandBG API - 随机背景图片服务

在线体验

特性

API 文档

GET /api/random

GET /api/list

GET /manifest.json

技术栈