Upload Media - Imperial Documentation

Upload Media

curl --request POST \
  --url https://api.imperial.gay/images/upload \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{}'

import requests

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

payload = {}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({})
};

fetch('https://api.imperial.gay/images/upload', 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/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.imperial.gay/images/upload")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{}"

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

{
  "_id": "<string>",
  "url": "<string>",
  "thumbnailUrl": "<string>",
  "filename": "<string>",
  "originalFilename": "<string>",
  "fileSize": 123,
  "mimeType": "<string>",
  "compressed": true,
  "createdAt": "<string>"
}

POST

images

upload

Upload Media

curl --request POST \
  --url https://api.imperial.gay/images/upload \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{}'

import requests

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

payload = {}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({})
};

fetch('https://api.imperial.gay/images/upload', 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/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.imperial.gay/images/upload")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{}"

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

{
  "_id": "<string>",
  "url": "<string>",
  "thumbnailUrl": "<string>",
  "filename": "<string>",
  "originalFilename": "<string>",
  "fileSize": 123,
  "mimeType": "<string>",
  "compressed": true,
  "createdAt": "<string>"
}

Request

Headers

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.

string

required

Must be multipart/form-data for file uploads

Body

file

required

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

Response

string

Unique identifier for the upload

string

Direct CDN URL to access the uploaded file

string

Thumbnail URL (generated automatically for videos)

string

The stored filename

string

The original filename before upload

number

File size in bytes

string

MIME type of the uploaded file (e.g., image/jpeg, video/mp4)

boolean

Whether the file was compressed (only for images with auto-compress enabled)

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"

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

const form = new FormData();
form.append("file", fs.createReadStream("cat.jpg"));

const response = await axios.post("https://api.imperial.gay/images/upload", form, {
  headers: {
    Authorization: "Bearer imperial_live_xxxxxxxxxxxxx",
    ...form.getHeaders(),
  },
});

console.log(response.data);

import requests

url = 'https://api.imperial.gay/images/upload'
headers = {'Authorization': 'Bearer imperial_live_xxxxxxxxxxxxx'}
files = {'file': open('cat.jpg', 'rb')}

response = requests.post(url, headers=headers, files=files)
print(response.json())

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:

Tier	Storage	Monthly Operations
Free	1 GB	10,000
Starter	5 GB	100,000
Pro	10 GB	1,000,000
Business	200 GB	5,000,000

Upgrade your plan in the Dashboard to get more storage and operations.

​Request

​Headers

​Body

​Response

​Example Requests

​Example Response

​Video Upload Response

​Error Responses

​Storage Limit Exceeded

​Invalid File Type

​Unauthorized

​Features

​Auto-Compression

​Batch Uploads

​Storage Management

Request

Headers

Body

Response

Example Requests

Example Response

Video Upload Response

Error Responses

Storage Limit Exceeded

Invalid File Type

Unauthorized

Features

Auto-Compression

Batch Uploads

Storage Management