API Documentation

This page documents the ImgSmaller API for programmatic image compression. Use your personal API key from the Dashboard. Examples below use a dummy key for demonstration:

Overview

Base URL: https://imgsmaller.com
Auth: Send your key in X-API-Key header or ?api_key=... query.
Daily limit: Controlled by server setting. Exceeding returns HTTP 429.
Endpoints: GET /api/v1/info, POST /api/v1/compress

Authentication

Provide your API key via header or query parameter:

# Header
curl -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' https://imgsmaller.com/api/v1/info

# Query string
curl 'https://imgsmaller.com/api/v1/info?api_key=demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'

Missing or invalid keys return HTTP 401.

GET /api/v1/info

Returns capabilities and remaining quota.

curl -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' 'https://imgsmaller.com/api/v1/info'

# Example 200 response
{
  "endpoint": "https://imgsmaller.com/api/v1/compress",
  "remaining_today": 98,
  "reset_in_seconds": 3600,
  "limit": 100,
  "supported_input": ["jpeg","jpg","png","webp","avif"],
  "supported_output": ["jpeg","jpg","png","webp","avif","original"]
}

POST /api/v1/compress

Accepts either multipart form-data (file upload) or JSON body with file_base64 or file_url.

target_size: auto or e.g. 20KB (defaults to auto).
output: one of jpeg, jpg, png, webp, avif, or original (keeps input format).
file_url: requires your Dashboard “Allowed Domain”. If not set or host not allowed, returns 403.

Successful requests return 202 with a progress_key and result_url. Poll https://imgsmaller.com/result/{key} until ready.

Examples: output=jpeg

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=jpeg'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "jpeg"
  }'

Examples: output=jpg

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=jpg'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "jpg"
  }'

Examples: output=png

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=png'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "png"
  }'

Examples: output=avif

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=avif'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "avif"
  }'

Examples: output=webp

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=webp'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "webp"
  }'

Examples: output=original

cURL (multipart)

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -F 'file=@/path/to/image.jpg' \
  -F 'target_size=20KB' \
  -F 'output=original'

# 202 Accepted
{
  "queued": true,
  "progress_key": "abcd1234deadbeef",
  "result_url": "https://imgsmaller.com/result/abcd1234deadbeef",
  "download_url_template": "https://imgsmaller.com/download/{imageId}"
}

JSON body

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_base64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQA...",
    "target_size": "20KB",
    "output": "original"
  }'

Using file_url

For JSON with file_url, ensure your Dashboard → Allowed Domain is set (exactly one domain). Subdomains are allowed.

curl -X POST 'https://imgsmaller.com/api/v1/compress' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: demo_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  -d '{
    "file_url": "https://cdn.example.com/photo.jpg",
    "target_size": "auto",
    "output": "original"
  }'

# 403 if domain not allowed or not set
{
  "message": "No allowed domain set. Please set your allowed domain in dashboard."
}

Polling for Results

Use the result_url from the 202 response and poll until it returns the final JSON with download info.

curl 'https://imgsmaller.com/result/abcd1234deadbeef'

# Example when still processing
{"status":"processing"}

# Example when done
{
  "status": "done",
  "image_id": 12345,
  "download": "https://imgsmaller.com/download/12345",
  "bytes": 20480,
  "format": "webp"
}

Errors & Edge Cases

401: Missing/Invalid API key.
403: Disallowed or unset file_url domain.
413: File too large (see server’s UPLOAD_MAX_MB).
415/422: Unsupported or invalid image type.
429: Daily limit exceeded.
202: Accepted and queued; poll for completion.