Get Random Image

GET /api/images/random

Returns a random image from the photo collection for slideshow display.

Parameters

string

Specific folder path to get random image from. If not provided, selects from all images.

Request Examples

All Images

curl http://localhost:3000/api/images/random

Specific Folder

curl "http://localhost:3000/api/images/random?folder=vacation/2023"

Response

{
  "success": true,
  "data": {
    "imagePath": "/uploads/vacation/2023/beach.jpg",
    "fileName": "beach.jpg",
    "folder": "vacation/2023",
    "url": "/uploads/vacation/2023/beach.jpg",
    "metadata": {
      "size": 2048576,
      "dimensions": {
        "width": 1920,
        "height": 1080
      },
      "lastModified": "2023-07-15T10:30:00Z"
    }
  }
}

{
  "success": false,
  "error": "No images found in specified location",
  "code": "NO_IMAGES_AVAILABLE"
}

Response Fields

string

Server file path to the image

string

Original filename of the image

string

Folder path containing the image

string

Public URL path for accessing the image

object

Image metadata including size, dimensions, and modification date

Status Codes

Success

Random image retrieved successfully

Not Found

No images found in collection or specified folder

Server Error

Error accessing file system or processing images

Usage in Slideshow

async function loadRandomImage() {
  try {
    const response = await fetch('/api/images/random');
    const data = await response.json();
    
    if (data.success) {
      const img = document.getElementById('slideshow-image');
      img.src = data.data.url;
      img.alt = data.data.fileName;
    }
  } catch (error) {
    console.error('Failed to load image:', error);
  }
}

// Load new image every 5 seconds
setInterval(loadRandomImage, 5000);

Folder Filtering

When using the folder parameter:

Use forward slashes for nested folders: vacation/2023/summer
Folder paths are relative to the uploads directory
Invalid folder paths return no results
Empty folders return no results

Image Formats

Supported formats:

JPEG (.jpg, .jpeg)
PNG (.png)
GIF (.gif)
WebP (.webp)

REST API

Authentication

Photos API

Folders API

GET /api/images/random

Parameters

Request Examples

Response

Response Fields

Status Codes

Usage in Slideshow

Folder Filtering

Image Formats

​GET /api/images/random

​Parameters

​Request Examples

​Response

​Response Fields

​Status Codes

​Usage in Slideshow

​Folder Filtering

​Image Formats

GET /api/images/random

Parameters

Request Examples

Response

Response Fields

Status Codes

Usage in Slideshow

Folder Filtering

Image Formats