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 "file=@cat.jpg"

​
Example Response

{
  "_id": "67d8f9a1b2c3d4e5f6789012",
  "url": "https://origin.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://origin.imperial.gay/uploads/user-id/67d8f9a1b2c3d4e5f6789013-video.mp4",
  "thumbnailUrl": "https://origin.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 "file=@image1.jpg" \
  -F "file=@image2.jpg" \
  -F "file=@image3.jpg"
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.