Guppy Image API

This API provides random images of guppy.

Endpoints

Get a Random Guppy Image

GET /random-image

Returns a randomly selected guppy image.

Request

Headers:

Accept: application/json  (optional)

Response

If Accept header is application/json:

{
    "url": "https://res.cloudinary.com/your_cloud_name/image/upload/v12345/guppy_images/example.jpg",
    "publicId": "guppy_images/example"
}

If no Accept header is specified, the API returns the image directly.

Get Total Image Count

GET /api/images/count

Returns the total count of available images.

Response

{
    "count": 150,
    "lastRefreshed": "2025-02-26T12:00:00.000Z"
}

Force Refresh Image Cache

GET /admin/refresh-cache

Forces the API to refresh the list of images from Cloudinary.

Response

{
    "success": true,
    "count": 155,
    "lastRefreshed": "2025-02-26T12:10:00.000Z"
}

Error Responses

Errors are returned in JSON format with appropriate HTTP status codes.

Example: No Images Found

{
    "error": "No images found."
}

Example: Server Error

{
    "error": "Failed to retrieve random guppy image"
}

Usage Examples

Fetch a Random Image (JSON response)

curl -H "Accept: application/json" https://guppy.tsrs.tech/random-image

Fetch a Random Image (Direct Image)

curl -o guppy.jpg https://guppy.tsrs.tech/random-image

Get Image Count

curl https://guppy.tsrs.tech/api/images/count

Force Cache Refresh

curl https://guppy.tsrs.tech/admin/refresh-cache

About

This API was built by the guppy fan club.