API Documentation
Everything you need to integrate the Compresto Image Compression API.
Authentication
All API requests require an API key. Include your key in the X-API-Key header:
curl -H "X-API-Key: ck_your_api_key" https://api.compresto.app/v1/compress
Base URL
https://api.compresto.appEndpoints
POST/v1/compress
Compress an image file.
Request (Multipart)
curl -X POST https://api.compresto.app/v1/compress \ -H "X-API-Key: ck_your_api_key" \ -F "image=@photo.jpg" \ -F "quality=80" \ -F "format=webp" \ -F "maxWidth=1920" \ -o compressed.webp
Request (JSON/URL)
curl -X POST https://api.compresto.app/v1/compress \
-H "X-API-Key: ck_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/image.jpg",
"quality": 80,
"format": "webp"
}'Request (JSON/Base64)
curl -X POST https://api.compresto.app/v1/compress \
-H "X-API-Key: ck_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"image": "data:image/png;base64,iVBORw0KGgo...",
"quality": 80,
"format": "webp"
}'Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
image | file/string | * | Image file (multipart) or base64 string |
url | string | * | Public image URL (http/https) |
quality | number | 80 | 1-100, compression quality |
format | string | "auto" | "jpeg", "png", "webp", or "auto" |
maxWidth | number | null | Max width (preserves aspect ratio) |
maxHeight | number | null | Max height (preserves aspect ratio) |
* One of image (file/base64) or url is required. Priority: file upload > url > base64.
Response
Returns compressed image binary with stats in headers:
HTTP/1.1 200 OK Content-Type: image/webp X-Original-Size: 2048576 X-Compressed-Size: 512000 X-Savings-Percent: 75 X-Output-Format: webp <binary image data>
GET/v1/usage
Get current usage statistics.
curl https://api.compresto.app/v1/usage \ -H "X-API-Key: ck_your_api_key"
Response
{
"plan": "free",
"usage": {
"current": 47,
"limit": 100,
"resetAt": "2025-02-01T00:00:00Z"
},
"totals": {
"bytesIn": 52428800,
"bytesOut": 15728640,
"savedBytes": 36700160,
"savedPercent": 70
}
}GET/health
Check API status (no authentication required).
curl https://api.compresto.app/health
Error Codes
| Code | Meaning |
|---|---|
| 400 | Bad request (invalid parameters, blocked URL, invalid URL format) |
| 401 | Unauthorized (missing or invalid API key) |
| 413 | File too large (>10MB for free tier) |
| 415 | Unsupported image format |
| 429 | Rate limit exceeded (per-minute) or monthly quota exceeded |
| 500 | Internal server error |
| 502 | Failed to fetch image from URL |
| 504 | URL fetch timed out |
Rate Limits
The API enforces per-user rate limits based on your subscription tier:
| Plan | Rate Limit | Monthly Quota |
|---|---|---|
| Free | 60 req/min | 500 requests |
| Pro | 60 req/min | 5,000 requests |
| Business | 200 req/min | 50,000 requests |
- Rate limits are enforced per API key
- Monthly quotas reset on the 1st of each month
- Check your current usage via the
/v1/usageendpoint
Support
Questions? Email us at support@compresto.app