隨機圖片與訪客圖庫

兩個功能都在以下位置設定：

System Settings -> Other Settings

隨機圖片 API

隨機圖片 API 會從指定目錄中回傳一個隨機檔案，適合用於網站背景、頭像輪播，或外部頁面的隨機圖片呼叫。

啟用後，使用：

https://your-domain.com/random

隨機圖片 API 設定

選項	用途
啟用	開啟或關閉 /random 端點。關閉時會禁止存取。
目錄	限制隨機 API 可使用哪些目錄。未包含在這裡的目錄無法被 API 使用。
呼叫示範	產生可直接複製的隨機 API 連結。

你可以選擇多個目錄。例如只允許 /landscape/ 和 /portrait/ 時，隨機 API 只能從這些目錄及其子目錄中選取檔案。

隨機圖片 API 參數

參數	範例	用途
dir	/landscape/	指定隨機目錄。
content	image	指定媒體類型。可使用 image、video、audio，或以逗號組合。
orientation	auto	篩選圖片方向。可使用 portrait、landscape 或 auto。
type	url	回傳格式。空值表示重新導向，url 回傳純文字 URL，json 回傳 JSON。
origin	1	搭配 type=url 使用，回傳完整 URL。
age	all-ages,r12	依年齡分級篩選。
tag	wallpaper,sky	只回傳包含這些標籤的檔案。
ex	private	排除包含這些標籤的檔案。

回傳格式

不帶 type 時，API 會直接重新導向到隨機檔案 URL。

使用 type=url 時，會回傳文字 URL。

使用 type=json 時，會回傳檔案資訊，包括檔案 URL、檔案 ID、檔名、檔案類型、標籤、分級和相關中繼資料。

存取規則

隨機圖片 API 會遵守公開存取規則：

規則	效果
目錄限制	只能選取允許目錄中的檔案。
封鎖清單	封鎖清單中的檔案會排除在隨機池之外。
允許清單模式	啟用後，只會回傳允許公開存取的檔案。
年齡分級	R12、R16、R18 等內容會依目前存取模式篩選。

如果篩選後沒有符合的檔案，API 不會回傳符合結果。

快取

隨機圖片 API 會快取目錄候選池以提高速度。

檔案變更後，ImgHost 會更新目錄快取版本，後續請求會重新建立候選池。空目錄會短暫快取，以避免重複查詢。

訪客圖庫

訪客圖庫提供唯讀的公開瀏覽頁面，讓訪客查看你允許公開的目錄。

啟用後，訪客可以開啟：

https://your-domain.com/browse/directory-name

訪客圖庫設定

選項	用途
啟用	開啟或關閉訪客圖庫。關閉後，訪客無法瀏覽。
圖片載入模式	控制預覽使用原圖或縮圖。
開放目錄	設定訪客可以存取哪些目錄。

圖片載入模式

模式	用途
原圖	訪客頁面直接載入原始檔案。
縮圖	訪客頁面優先使用縮圖以加快載入。

開放目錄

開放目錄決定訪客可以看到哪些內容。

例如：

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

訪客接著可以存取：

https://your-domain.com/browse/1
https://your-domain.com/browse/2
https://your-domain.com/browse/landscape
https://your-domain.com/browse/portrait

也可以開放子目錄，例如 /2026/lucky/。訪客會被阻擋在未開放的目錄之外。

訪客圖庫功能

功能	說明
瀏覽目錄	查看開放目錄中的檔案和子目錄。
搜尋	依檔名、檔案 ID 或標籤搜尋。
類型篩選	篩選圖片、影片、音訊或其他檔案。
標籤篩選	包含或排除選定標籤。
方向篩選	篩選橫向或直向圖片。
時間篩選	依上傳時間範圍篩選。
副檔名篩選	依副檔名篩選。
複製連結	複製檔案存取連結。
媒體預覽	在訪客頁面查看或播放圖片、影片和音訊。

訪客圖庫存取規則

訪客圖庫同樣遵守公開存取規則：

規則	效果
開放目錄	只顯示允許的目錄。
存取模式	內容會依目前年齡分級存取模式篩選。
允許清單模式	啟用後，只顯示允許公開存取的檔案。
封鎖清單	封鎖清單中的檔案會被隱藏。