List Media

List Media

curl --request GET \
  --url https://api.imperial.gay/images \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.imperial.gay/images', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.imperial.gay/images",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.imperial.gay/images"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.imperial.gay/images")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "images": [
    {}
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123
  },
  "_id": "<string>",
  "url": "<string>",
  "thumbnailUrl": {},
  "mimeType": "<string>",
  "prompt": "<string>",
  "modelName": "<string>",
  "createdAt": "<string>",
  "type": "<string>"
}

GET

images

List Media

curl --request GET \
  --url https://api.imperial.gay/images \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://api.imperial.gay/images', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.imperial.gay/images",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.imperial.gay/images"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.imperial.gay/images")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "images": [
    {}
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123
  },
  "_id": "<string>",
  "url": "<string>",
  "thumbnailUrl": {},
  "mimeType": "<string>",
  "prompt": "<string>",
  "modelName": "<string>",
  "createdAt": "<string>",
  "type": "<string>"
}

Request

Headers

string

required

Your API key in the format: Bearer imperial_live_xxxxxxxxxxxxx

Query Parameters

number

default:"1"

Page number for pagination

number

default:"50"

Number of items per page (max: 100)

string

default:"active"

Filter by status: active, trash, or all

string

Filter by folder. For active status, leaving this empty shows Root by default.

string

Search across your whole library (filename/original filename, plus tag exact match)

string

Date filter start (YYYY-MM-DD, UTC)

string

Date filter end (YYYY-MM-DD, UTC)

string

MIME prefix filter (e.g. image/, video/, application/) or other

number

Minimum file size in bytes

number

Maximum file size in bytes

boolean

Filter favorites (true or false)

string

Include tags (comma-separated). Must include all tags.

string

Exclude tags (comma-separated)

Back-compat: tag=foo is still supported and behaves like tags=foo.

Response

array

Array of media objects (images and videos)

object

Pagination information

Show pagination properties

number

Current page number

number

Items per page

number

Total number of items

number

Total number of pages

Example Requests

curl -X GET "https://api.imperial.gay/images?page=1&limit=20" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"

const axios = require("axios");

const response = await axios.get("https://api.imperial.gay/images", {
  headers: {
    Authorization: "Bearer imperial_live_xxxxxxxxxxxxx",
  },
  params: {
    page: 1,
    limit: 20,
  },
});

console.log(response.data);

import requests

url = 'https://api.imperial.gay/images'
headers = {'Authorization': 'Bearer imperial_live_xxxxxxxxxxxxx'}
params = {'page': 1, 'limit': 20}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Example Response

{
  "images": [
    {
      "_id": "67d8f9a1b2c3d4e5f6789012",
      "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789012-cat.jpg",
      "thumbnailUrl": null,
      "mimeType": "image/jpeg",
      "prompt": "cat.jpg",
      "modelName": "240.1KB",
      "size": {
        "width": 0,
        "height": 0
      },
      "createdAt": "2026-01-07T12:34:56.789Z",
      "type": "upload"
    },
    {
      "_id": "67d8f9a1b2c3d4e5f6789013",
      "url": "https://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
      "thumbnailUrl": "https://origin.imperial.gay/uploads/user-id/thumbs/67d8f9a1b2c3d4e5f6789013-thumb.jpg",
      "mimeType": "video/mp4",
      "prompt": "video.mp4",
      "modelName": "5.0MB",
      "size": {
        "width": 0,
        "height": 0
      },
      "createdAt": "2026-01-07T12:35:00.123Z",
      "type": "upload"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 245,
    "totalPages": 13
  }
}

Media Object Fields

string

Unique identifier for the media

string

Direct CDN URL to the media file

string | null

Thumbnail URL (for videos only, null for images)

string

MIME type (e.g., image/jpeg, video/mp4)

string

Original filename

string

File size displayed in human-readable format

string

ISO 8601 timestamp of upload

string

Always "upload" for user uploads

Pagination

The API returns up to 50 items per page by default. Use the page and limit parameters to navigate through your media:

# Get page 2 with 100 items per page
curl -X GET "https://api.imperial.gay/images?page=2&limit=100" \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx"

Filtering

Currently, the API returns all media sorted by upload date (newest first). Additional filtering options will be added in future updates.

Error Responses

Unauthorized

{
  "error": "Unauthorized",
  "statusCode": 401
}

Invalid Parameters

{
  "error": "Invalid page or limit parameter",
  "statusCode": 400
}

Use this endpoint to build custom galleries or dashboards for your media library.

Authentication

Endpoints

Request

Headers

Query Parameters

Response

Example Requests

Example Response

Media Object Fields

Filtering

Error Responses

Unauthorized

Invalid Parameters

​Request

​Headers

​Query Parameters

​Response

​Example Requests

​Example Response

​Media Object Fields

​Pagination

​Filtering

​Error Responses

​Unauthorized

​Invalid Parameters

Request

Headers

Query Parameters

Response

Example Requests

Example Response

Media Object Fields

Pagination

Filtering

Error Responses

Unauthorized

Invalid Parameters