Azure

Azure API

随机图片接入文档

通过英文分类和图片池路径获取随机图片。全部、PC 和移动端三个入口返回的图片都可以自适应容器，入口差异只决定从哪些素材中随机选择。

01

核心概念

英文分类
一级图片集合，例如 zzz、wallpaper。分类名只使用小写英文字母、数字和连字符。
图片池入口
每个分类固定提供 all、pc、mobile 三个入口，不能创建第四种入口。
素材用途
后台可将图片标记为通用素材、PC 素材或移动端素材，用于决定它进入哪个定向图片池。
响应式显示
三个入口的最终图片都使用相同的 CSS 响应式规则。PC 与移动端只筛选素材方向，不限制展示尺寸。

all 不是一种素材类型。 它是汇总入口，会从该英文分类的全部启用图片中选择，包括通用、PC 和移动端素材。

02

快速开始

将随机地址直接放入 img 的 src。接口先返回 302，再由浏览器自动请求最终图片，不需要手动处理跳转。

index.html
html
<div class="azure-frame">
  <img
    src="https://your-domain.com/zzz/all?width=1280&format=webp"
    alt="随机壁纸"
  />
</div>

示例中的 1280 适合约 640 CSS 像素宽的高分屏容器。普通屏幕可以选择更接近实际容器宽度的档位。

03

接口路径

推荐使用简短路径。显式 API 路径行为相同，适合需要统一管理接口前缀的客户端。

/{category}/all

全部图片

该分类全部启用图片

通用、PC、移动端素材都会参与随机，显示时始终自适应容器。

/{category}/pc

PC 图片

仅 PC 素材

优先获得横屏素材，仍可在任意尺寸容器中响应式显示。

/{category}/mobile

移动端图片

仅移动端素材

优先获得竖屏素材，仍会跟随容器宽高铺满显示。

简短路径
url
https://your-domain.com/zzz/pc
显式 API 路径
url
https://your-domain.com/api/random/zzz/pc

/{category} 是 /{category}/all 的简写；根路径 /api/random 会从全部分类中随机选择。

04

请求参数

字段位置是否必填说明
category路径分类路径必填小写英文分类，例如 zzz、anime-wallpaper。
mode路径可选仅允许 all、pc、mobile；省略时等同于 all。
seed查询参数可选相同分类、入口和 seed 会稳定选择同一张启用图片。
width查询参数可选本地图支持 320、640、960、1280、1600 档位，请求值会向上匹配最近档位。
format查询参数可选当前支持 webp，必须与 width 一起使用；外部图片链接保持源站地址。
完整参数示例
url
https://your-domain.com/zzz/pc?seed=homepage&width=1280&format=webp
05

响应式显示

响应式由页面容器决定，与图片来自 all、pc 还是 mobile 无关。以下样式让图片与框体保持相同宽高，并使用 cover 裁切超出部分。

styles.css
css
.azure-frame {
  width: 100%;
  aspect-ratio: 16 / 9;
  overflow: hidden;
  background: #f5f5f7;
}

.azure-frame img {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}
横向展示框优先调用 pc，素材构图更适合 16:9、3:2 等宽容器。
竖向展示框优先调用 mobile，素材构图更适合 9:16、3:4 等高容器。
任意展示框调用 all 获取完整图片池，再由 object-fit: cover 适配实际框体。
06

更多示例

固定到同一张图片
url
https://your-domain.com/zzz/all?seed=article-cover&width=1280&format=webp
JavaScript 换一张
javascript
const image = document.querySelector("#random-image");

function refreshImage() {
  image.src = `https://your-domain.com/zzz/all?width=1280&format=webp&t=${Date.now()}`;
}
CSS 背景图
css
.hero {
  min-height: 420px;
  background-image: url("https://your-domain.com/zzz/pc?width=1600&format=webp");
  background-position: center;
  background-size: cover;
}
07

缓存与性能

随机地址与最终图片使用不同的缓存策略。随机地址每次重新选图；最终本地图片可以被浏览器和代理长期缓存。

随机接口Cache-Control: no-store避免浏览器缓存 302 结果，刷新时可以重新随机。
最终本地图immutable + ETag图片变体长期缓存；再次验证未变化时返回 304。
WebP 变体按需生成并落盘首次请求生成对应宽度，后续请求直接读取缓存文件。
宽度建议接近容器像素宽度高分屏可使用容器 CSS 宽度的约 2 倍，避免下载完整原图。
08

状态码

状态码含义处理方式
302随机成功浏览器自动跟随 Location 加载最终图片。
304图片未变化继续使用浏览器缓存，无需重新传输图片内容。
400请求参数错误检查分类、mode、width 和 format 的取值。
404图片池为空确认分类存在，并为对应 PC 或移动端图片池添加启用素材。
500服务内部错误稍后重试，并在管理员后台检查服务与存储状态。

PC 或移动端图片池为空时会返回 404，不会自动回退到另一种素材；all 只要该分类仍有任意启用图片即可工作。

09

常见问题

只有 all 入口支持自适应吗？
不是。all、pc、mobile 返回的图片都可以使用同一套 width、height 和 object-fit 样式自适应容器。
all 入口包含哪些图片？
包含当前英文分类下全部启用图片，不区分后台标记的通用、PC 或移动端素材用途。
PC 图片能在手机上显示吗？
可以。PC 表示原始素材更适合横向构图，并不限制访问设备；最终图片仍会按照手机上的容器尺寸响应式显示。
为什么相同地址会出现不同图片？
未设置 seed 时，每次请求都会重新随机。需要稳定图片时添加固定 seed；需要主动换图时更换 seed 或附加时间参数。

管理分类、素材用途和图片池状态

进入图片库