随机图像 API 与访客图库

这两个功能都在：

系统配置 -> 其他设置

随机图像 API

随机图像 API 用来从指定目录里随机取出一个文件，适合做站点背景图、头像轮播、外部页面随机图片调用。

开启后可以访问：

https://你的域名/random

随机图像 API 设置

选项	作用
启用	开启或关闭 /random 接口。关闭时访问会返回禁止访问。
目录	限制随机接口可以从哪些目录取文件。未包含在这里的目录不能被随机接口调用。
调用演示	帮你生成随机图接口链接，可直接复制使用。

目录可以选择多个。比如只允许 /landscape/ 和 /portrait/，随机接口就只能从这两个目录或它们的子目录里取文件。

随机图像 API 参数

参数	示例	作用
dir	/landscape/	指定随机目录。
content	image	指定媒体类型，可用 image、video、audio，也可用逗号组合。
orientation	auto	图片方向筛选，可用 portrait、landscape、auto。
type	url	返回格式。留空为跳转，url 返回纯链接，json 返回 JSON 数据。
origin	1	配合 type=url 使用，返回完整链接。
age	all-ages,r12	年龄分级筛选。
tag	wallpaper,sky	只随机包含这些标签的文件。
ex	private	排除包含这些标签的文件。

返回格式

默认不带 type 时，接口会直接跳转到随机文件地址。

type=url 时返回文本链接。

type=json 时返回文件信息，包括文件链接、文件 ID、文件名、文件类型、标签、分级等。

访问限制

随机图像 API 会遵守后台的公开访问规则：

规则	效果
目录限制	只能随机“目录”里允许的文件。
黑名单	黑名单文件不会进入随机池。
白名单模式	开启白名单模式后，只会返回允许公开访问的文件。
年龄分级	会按当前访问模式过滤 R12、R16、R18 等内容。

如果筛选后没有可用文件，会返回没有匹配结果。

缓存说明

随机图像 API 会缓存目录候选池，提高访问速度。

文件变化后系统会更新目录缓存版本，后续请求会重新生成候选池。空目录会短时间缓存，避免反复查询。

访客图库

访客图库用于开放一个只读的公开浏览页面，让访客查看你允许公开的目录。

开启后可以访问：

https://你的域名/browse/目录名

访客图库设置

选项	作用
启用	开启或关闭访客图库。关闭后访客无法浏览。
图像加载模式	控制访客图库里图片预览使用原图还是缩略图。
开放目录	设置访客可以访问哪些目录。

图像加载模式

模式	作用
原图	访客页面直接加载原文件。
缩略图	访客页面优先加载缩略图，页面打开更快。

开放目录

开放目录决定访客能看到哪些内容。

例如填写：

/1/,/2/,/landscape/,/portrait/

访客就可以访问这些目录：

https://你的域名/browse/1
https://你的域名/browse/2
https://你的域名/browse/landscape
https://你的域名/browse/portrait

也可以开放子目录，例如 /2026/lucky/。访客访问未开放的目录会被拒绝。

访客图库能做什么

访客图库支持：

功能	说明
浏览目录	查看开放目录里的文件和子目录。
搜索	按文件名、文件 ID、标签搜索。
类型筛选	筛选图片、视频、音频或其他文件。
标签筛选	包含指定标签或排除指定标签。
方向筛选	筛选横图或竖图。
时间筛选	按上传时间范围筛选。
扩展名筛选	按文件扩展名筛选。
复制链接	复制文件访问链接。
预览媒体	图片、视频、音频可在访客页查看或播放。

访客图库访问规则

访客图库同样会遵守公开访问规则：

规则	效果
开放目录	只显示允许开放的目录。
访问模式	按当前年龄分级访问模式过滤内容。
白名单模式	开启后只显示允许公开访问的文件。
黑名单	黑名单文件不会显示。