Skip to main content
POST
https://api.imperial.gay
/
images
/
upload
Upload Media
curl --request POST \
  --url https://api.imperial.gay/images/upload \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{}'
{
  "_id": "<string>",
  "url": "<string>",
  "thumbnailUrl": "<string>",
  "filename": "<string>",
  "originalFilename": "<string>",
  "fileSize": 123,
  "mimeType": "<string>",
  "compressed": true,
  "createdAt": "<string>"
}

Request

Headers

Authorization
string
required
Your authentication token in one of these formats:
  • API Key (Pro/Business): Bearer imperial_live_xxxxxxxxxxxxx
  • Upload Key (Free/Starter): Bearer imperial_upload_xxxxxxxxxxxxx
See Authentication for more details.
Content-Type
string
required
Must be multipart/form-data for file uploads

Body

file
file
required
The image or video file to upload. Supports:
  • Images: JPEG, PNG, WebP, GIF
  • Videos: MP4, WebM, MOV, AVI

Response

_id
string
Unique identifier for the upload
url
string
Direct CDN URL to access the uploaded file
thumbnailUrl
string
Thumbnail URL (generated automatically for videos)
filename
string
The stored filename
originalFilename
string
The original filename before upload
fileSize
number
File size in bytes
mimeType
string
MIME type of the uploaded file (e.g., image/jpeg, video/mp4)
compressed
boolean
Whether the file was compressed (only for images with auto-compress enabled)
createdAt
string
ISO 8601 timestamp of upload

Example Requests

curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "[email protected]"

Example Response

{
  "_id": "67d8f9a1b2c3d4e5f6789012",
  "url": "https://cdn.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789012-cat.jpg",
  "filename": "67d8f9a1b2c3d4e5f6789012-cat.jpg",
  "originalFilename": "cat.jpg",
  "fileSize": 245678,
  "mimeType": "image/jpeg",
  "compressed": true,
  "createdAt": "2026-01-07T12:34:56.789Z"
}

Video Upload Response

When uploading a video, a thumbnail is automatically generated:
{
  "_id": "67d8f9a1b2c3d4e5f6789013",
  "url": "https://cdn.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
  "thumbnailUrl": "https://cdn.imperial.gay/uploads/user-id/thumbs/67d8f9a1b2c3d4e5f6789013-thumb.jpg",
  "filename": "67d8f9a1b2c3d4e5f6789013-video.mp4",
  "originalFilename": "video.mp4",
  "fileSize": 5242880,
  "mimeType": "video/mp4",
  "compressed": false,
  "createdAt": "2026-01-07T12:35:00.123Z"
}

Error Responses

Storage Limit Exceeded

{
  "error": "Storage limit exceeded. You've used 4.8 GB of 5 GB.",
  "statusCode": 413
}

Invalid File Type

{
  "error": "Only images and videos are allowed",
  "statusCode": 400
}

Unauthorized

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

Features

Auto-Compression

Enable auto-compression in your Dashboard Settings to automatically compress images on upload:
  • JPEG: Compressed with customizable quality (default: 80%)
  • PNG: Optimized compression level 9
  • WebP: Compressed with quality setting
Videos are never compressed to preserve quality.

Batch Uploads

You can upload multiple files in a single request by including multiple file fields:
curl -X POST https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]"
The response will contain an array of upload results.

Storage Management

Uploads count towards your storage limit based on your subscription tier:
TierStorageMonthly Operations
Free1 GB10,000
Starter5 GB100,000
Pro10 GB1,000,000
Business200 GB5,000,000
Upgrade your plan in the Dashboard to get more storage and operations.