API Documentation

Quick Start

Compress your first image in under a minute. All you need is an API key.

cURL

curl -X POST https://api.octosqueeze.com/api/v1/compress \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/image.jpg" \
  -F "mode=balanced"

Base URL: https://api.octosqueeze.com/api/v1

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

HTTP Header

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your dashboard. Keep your API keys secure and never expose them in client-side code.

Security: Never commit API keys to version control or expose them in frontend code.

Compress Image

POST /api/v1/compress

Compress an image by uploading a file or providing a URL. Returns compression results and a temporary download URL.

Option 1: File Upload

Send a multipart/form-data request with the image file:

HTTP

POST /api/v1/compress HTTP/1.1
Host: api.octosqueeze.com
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

file: [binary image data]
format: webp
mode: balanced

Option 2: URL

Send a JSON request with an image URL:

JSON

{
  "url": "https://example.com/image.jpg",
  "format": "webp",
  "mode": "balanced"
}

Batch Compression

POST /api/v1/compress-batch

Compress multiple images from URLs in a single request (up to 100 images).

JSON

{
  "items": [
    {
      "url": "https://example.com/image1.jpg",
      "image_id": "my-id-1",
      "options": { "mode": "size", "format": "webp" }
    },
    {
      "url": "https://example.com/image2.png",
      "image_id": "my-id-2"
    }
  ],
  "options": {
    "mode": "balanced",
    "format": "webp"
  }
}

The options at the root level apply to all items. Per-item options override the defaults.

Check Status

GET /api/v1/status/{'{jobId}'}

Check the status of a compression job.

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "original_size": 2457600,
    "compressed_size": 491520,
    "savings_percent": 80,
    "format": "webp",
    "download_url": "https://api.octosqueeze.com/api/v1/download/550e8400...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Download

GET /api/v1/download/{'{id}'}

Download a compressed image. Returns the binary file data.

Guest uploads are automatically cleaned up after 24 hours. Store the compressed image on your own servers.

Usage & Account

Get Usage Statistics

GET /api/v1/usage

Response

{
  "success": true,
  "data": {
    "plan": "Pro",
    "compressions_used": 1250,
    "compressions_limit": 25000,
    "api_calls_today": 150,
    "api_calls_limit": 10000,
    "bytes_saved": 524288000,
    "max_file_size_mb": 50,
    "formats": ["jpeg", "png", "webp", "avif"],
    "reset_date": "2024-02-01"
  }
}

Get Account Info

GET /api/v1/account

Returns account details including subscription status and API key limits.

Parameters

Parameter	Type	Required	Description
`file`	File	Required*	Image file (JPEG, PNG, WebP). Required if `url` not provided.
`url`	String	Required*	Image URL. Required if `file` not provided.
`format`	String	Optional	Output: `jpeg`, `png`, `webp`, `avif`. Default: same as input
`mode`	String	Optional	`size`, `balanced` (default), `quality`
`quality`	Integer	Optional	1-100. Overrides mode.
`width`	Integer	Optional	Max width (px). Aspect ratio preserved.
`height`	Integer	Optional	Max height (px). Aspect ratio preserved.
`strip_metadata`	Boolean	Optional	Remove EXIF data. Default: false

Response Format

Successful responses return JSON with compression results:

200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "compressed": true,
    "original_size": 2457600,
    "compressed_size": 491520,
    "savings_bytes": 1966080,
    "savings_percent": 80,
    "format": "webp",
    "download_url": "https://api.octosqueeze.com/api/v1/download/550e8400..."
  }
}

Guest uploads are automatically deleted after 24 hours. Store the compressed image on your own servers.

Code Examples

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.octosqueeze.com/api/v1/compress',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY'
    ],
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('/path/to/image.jpg'),
        'format' => 'webp',
        'mode' => 'balanced'
    ]
]);

$response = curl_exec($curl);
$result = json_decode($response, true);

if ($result['success']) {
    $downloadUrl = $result['data']['download_url'];
    file_put_contents('compressed.webp', file_get_contents($downloadUrl));
}

curl_close($curl);

Node.js

JavaScript

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

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/image.jpg'));
form.append('format', 'webp');
form.append('mode', 'balanced');

const response = await axios.post(
    'https://api.octosqueeze.com/api/v1/compress',
    form,
    {
        headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            ...form.getHeaders()
        }
    }
);

if (response.data.success) {
    const downloadUrl = response.data.data.download_url;
    // Download and save the compressed image
}

Python

import requests

url = 'https://api.octosqueeze.com/api/v1/compress'
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

with open('/path/to/image.jpg', 'rb') as f:
    files = {'file': f}
    data = {'format': 'webp', 'mode': 'balanced'}
    response = requests.post(url, headers=headers, files=files, data=data)

result = response.json()
if result['success']:
    download_url = result['data']['download_url']
    compressed = requests.get(download_url)
    with open('compressed.webp', 'wb') as f:
        f.write(compressed.content)

Rate Limits

API requests are rate limited based on your plan:

Plan	Req/Min	Calls/Day	Monthly	Max File
Free	20	200	500	25 MB
Starter	60	1,000	5,000	25 MB
Pro	120	10,000	25,000	50 MB
Unlimited	300	Unlimited	Unlimited	100 MB
Enterprise	1,000	Unlimited	Unlimited	200 MB

Rate limit headers are included in all responses:

X-RateLimit-Limit - Maximum requests per minute
X-RateLimit-Remaining - Remaining requests this minute
X-RateLimit-Reset - Seconds until the rate limit resets
Retry-After - Seconds to wait before retrying (when rate limited)

Error Handling

Error responses include a status code and descriptive message:

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_file_type",
    "message": "Unsupported file type. Please upload JPEG, PNG, or WebP."
  }
}

HTTP Status Codes

Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`413`	File too large
`429`	Rate limit exceeded
`500`	Server error