Skip to main content

​
Authentication by Tier

Imperial offers different authentication types based on your subscription tier:
Upload Keys OnlyFree and Starter tiers receive an upload key that can only be used for uploading images and videos. Upload keys cannot access other API endpoints.
  • Limited to POST /images/upload endpoint only
  • Perfect for ShareX, Imperial Shot, and other custom uploaders
  • Manage in Settings → Security section
Want full API access? Upgrade to Pro or Business to unlock all API endpoints, create multiple API keys, and access detailed request analytics.

​
Upload Keys (Free & Starter)

Upload keys are restricted authentication tokens that only allow file uploads.

​
Getting Your Upload Key

  1. Log into your Dashboard
  2. Navigate to Settings → Security
  3. Your upload key is displayed (starts with imperial_upload_)
  4. Click Regenerate Upload Key if you need a new one
Regenerating your upload key will invalidate the old one. You’ll need to update it in ShareX and other uploaders.
Upload keys don’t provide request analytics or detailed logging. Upgrade to Pro to access API keys with full analytics, latency tracking, and request logs.

​
Using Upload Keys

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

​
API Keys (Pro & Business)

API keys provide full access to all Imperial endpoints.

​
Creating an API Key

  1. Log into your Dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Give your key a descriptive name
  5. Copy the key immediately (it’s only shown once)
Store your API key securely. It starts with imperial_live_ and provides full access to your account.

​
Authentication Methods

Imperial supports two authentication methods: Include your API key in the Authorization header: 
curl https://api.imperial.gay/images/upload \
  -H "Authorization: Bearer imperial_live_xxxxxxxxxxxxx" \
  -F "[email protected]"

​
JWT Token (For dashboard/web apps)

JWT tokens are obtained through login and used internally by the dashboard. For API integrations, use API keys instead.

​
Base URL

All API endpoints are relative to: 
https://api.imperial.gay

​
Rate Limits

Rate limits depend on your subscription tier and authentication type:
TierAuthenticationRequests per Minute
FreeUpload Key60
StarterUpload Key120
ProAPI Key300
BusinessAPI Key1000
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1704639600

​
Error Responses

Imperial uses standard HTTP status codes:
CodeMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found
413Payload Too Large - File exceeds storage limit
429Too Many Requests - Rate limit exceeded
500Internal Server Error

​
Error Response Format

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

​
CORS

The API supports CORS for browser-based applications. All origins are allowed for GET requests. POST/DELETE requests require authentication.

​
Content Types

  • Upload endpoints accept multipart/form-data
  • All other endpoints accept and return application/json