Skip to main content
GET
/
images
List Media
curl --request GET \
  --url https://api.imperial.gay/images \
  --header 'Authorization: <authorization>'
{
  "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

​
Authorization
string
required
Your API key in the format: Bearer imperial_live_xxxxxxxxxxxxx

​
Query Parameters

​
page
number
default:"1"
Page number for pagination
​
limit
number
default:"50"
Number of items per page (max: 100)
​
status
string
default:"active"
Filter by status: active, trash, or all
​
folderId
string
Filter by folder. For active status, leaving this empty shows Root by default.
​
q
string
Search across your whole library (filename/original filename, plus tag exact match)
​
from
string
Date filter start (YYYY-MM-DD, UTC)
​
to
string
Date filter end (YYYY-MM-DD, UTC)
​
mimePrefix
string
MIME prefix filter (e.g. image/, video/, application/) or other
​
minSize
number
Minimum file size in bytes
​
maxSize
number
Maximum file size in bytes
​
favorite
boolean
Filter favorites (true or false)
​
tags
string
Include tags (comma-separated). Must include all tags.
​
excludeTags
string
Exclude tags (comma-separated)
Back-compat: tag=foo is still supported and behaves like tags=foo.

​
Response

​
images
array
Array of media objects (images and videos)
​
pagination
object
Pagination information

​
Example Requests

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

​
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

​
_id
string
Unique identifier for the media
​
url
string
Direct CDN URL to the media file
​
thumbnailUrl
string | null
Thumbnail URL (for videos only, null for images)
​
mimeType
string
MIME type (e.g., image/jpeg, video/mp4)
​
prompt
string
Original filename
​
modelName
string
File size displayed in human-readable format
​
createdAt
string
ISO 8601 timestamp of upload
​
type
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.