Random Image API Documentation

Orientation Filter

Use the orientation parameter to prefer landscape/portrait/square images when selecting randomly.

• `orientation` = `landscape` | `portrait` | `square`
• Works for both /api/random (redirect) and /api/response (direct response).

Resize & Crop (Direct Response)

The /api/response endpoint supports resizing with optional cropping.

• `width` / `height` Single value keeps aspect ratio; both values combine with fit.
• `fit` = `cover` | `contain` (default cover)

Output Format & Quality

When enabled in the admin panel, callers can use format and quality to control output format and compression quality dynamically.

• `format` = `jpg` | `jpeg` | `webp`; when omitted, the original format is preserved.
• `quality` accepts either `0-1` decimals or `1-100` integers. For example, `0.8` and `80` both mean 80% quality.
• The admin panel can also configure default WebP delivery separately for `/api/random` and `/api/response`/`/image`, and the two switches are independent.
• When default WebP delivery is enabled for an endpoint, use `origin=true` to force the original transfer behavior.

Time Window Weighted Random

After an admin enables this parameter, callers can make images uploaded inside a selected time window more likely to be returned. Each image inside the window participates with timeWeight weight, while images outside keep base weight 1.

Enable “Time Window Weighting” in Admin Panel → API Configuration first. It applies to /api/random, /api/random?response=true, and /api/response.

• `timeWindow` supports rolling windows as a positive integer plus m/h/d/w, such as 30m, 24h, 7d, or 4w. Maximum: 365d.
• `timeStart` and `timeEnd` support a fixed time range. Use ISO datetimes with Z/+08:00, or pass `timeZone=Asia/Shanghai` / `timeZone=%2B08:00` when the datetimes do not include a zone.
• `timeWeight` is an integer from 1 to 100. 1 is equivalent to normal random selection; larger values increase the probability of images inside the window.
• Overall in-window hit rate = in-window image count × timeWeight / (in-window image count × timeWeight + out-of-window image count).
• `timeWeight=100` does not mean a guaranteed 100% in-window hit. If the window has few images and the outside pool is large, the overall in-window hit rate can still be modest.
• After the in-window bucket is selected, one matching image inside that window is chosen uniformly at random. Ordering is only used for stable pagination, not for preferring newest images.
• Do not combine timeWindow with timeStart/timeEnd. timeZone only applies to fixed windows. Missing timeWeight, missing window values, invalid dates/time zones, or disabled parameters return 400.