Random Image API Documentation

Simple and easy-to-use random image API service

API Access Links

Base API Address

/api/random

API Key Authentication (Optional)

If API Key authentication is enabled in the admin panel, all API requests must include the key parameter.

/api/random?key=your-api-key

You can enable and configure API Key in Admin Panel → API Configuration.

Usage Examples

Redirect Mode (/api/random)

/api/random

Direct Response Mode (/api/response)

/api/response

With Parameters (r18=r18)

.../random?r18=true

With Parameters (sfw=sfw)

.../random?sfw=true

Orientation & Size Filters

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).
/api/random?orientation=landscape
/api/response?orientation=landscape

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)
/api/response?width=800&height=600&fit=cover
/api/response?width=800&height=600&fit=contain

Transparency Adjustment Feature

endpoint supports image transparency adjustment. You can adjust image opacity and composite it onto a specified background color.

Parameter Description

  • opacity

    Image opacity (0-1.0)

    • 0 = fully transparent, 1 = fully opaque • Optional parameter, no transparency processing if not specified

  • bgColor

    Background color

    white | black | #hex

Examples

50% opacity, white background

/api/response?opacity=0.5&bgColor=white

80% opacity, black background

/api/response?opacity=0.8&bgColor=black

30% opacity, custom color background

/api/response?opacity=0.3&bgColor=ff6b6b

Response Format

Success Response (200 OK)

Content-Type: image/jpeg, image/png, image/webp

// Headers

X-Image-Id: ...

X-Image-Filename: ...

X-Response-Time: ...ms

Error Response

400400 Bad Request
403403 Forbidden
404404 Not Found
429429 Too Many Requests
500500 Internal Server Error

Notice

  • Rate Limit:API has request rate limits, please avoid making requests too frequently.
  • Cache:Image responses include cache headers, client-side caching is recommended for better performance.
  • HTTPS:HTTPS protocol is recommended for accessing the API to ensure security.