REST API v1.0

TinyJPG API Documentation

Optimize your images programmatically with our powerful, fast, and reliable API

Get Your API Key

Quick Start

Get started with the TinyJPG API in just a few simple steps. Our API allows you to optimize images programmatically, reducing file sizes by up to 70% without visible quality loss.

1. Get Your API Key

Sign up and generate your API key from the dashboard.

2. Make Your First Request

Upload an image and receive optimized results instantly.

Base URL
https://www.tinyjpg.co/api

All API requests require authentication using an API key in the X-API-Key header.

Image Optimization

POST /api/optimize

Upload and optimize an image file. The optimization process runs asynchronously, and you'll receive immediate feedback with URLs to access your optimized image.

Request Parameters
Parameter Type Required Description
image File Yes The image file to optimize (JPEG, PNG, GIF, or WebP)
quality Integer No Compression quality level (1-100, default is 80)
Example Request
cURL 
curl -X POST "https://www.tinyjpg.co/api/optimize" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  -F "quality=80"
Response
JSON 
{
  "success": true,
  "message": "Image uploaded and queued for optimization",
  "data": {
    "image_id": 123,
    "original_url": "https://www.tinyjpg.co/direct-file/original/sample_filename.jpg",
    "optimized_url": "https://www.tinyjpg.co/direct-file/optimized/sample_filename.jpg",
    "status": "processing",
    "original_size": 2048576,
    "estimated_optimized_size": 1024288
  }
}

Check Optimization Status

GET /api/status/{image_id}

Check the status of an optimization request. Use this endpoint to determine when an image has finished processing and get the final results.

Path Parameters
Parameter Type Description
image_id Integer The ID of the image returned from the optimize endpoint
Example Request
cURL 
curl -X GET "https://www.tinyjpg.co/api/status/123" \
  -H "X-API-Key: YOUR_API_KEY"
Response
JSON 
{
  "success": true,
  "data": {
    "image_id": 123,
    "status": "completed",
    "original_size": 2048576,
    "optimized_size": 1024288,
    "compression_ratio": 50.0,
    "processing_time": 2.34,
    "original_url": "https://www.tinyjpg.co/direct-file/original/sample_filename.jpg",
    "optimized_url": "https://www.tinyjpg.co/direct-file/optimized/sample_filename.jpg"
  }
}

Usage Statistics

GET /api/v1/usage

Get detailed usage information, including monthly trends, image type distribution, and compression statistics.

Example Request
cURL 
curl -X GET "https://www.tinyjpg.co/api/v1/usage" \
  -H "X-API-Key: YOUR_API_KEY"

Error Handling

Our API uses standard HTTP status codes to indicate success or failure. Each error response includes a detailed message explaining what went wrong.

Common Status Codes
Status Code Description
200 Success - Request completed successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - Plan limit exceeded or insufficient permissions
422 Unprocessable Entity - Validation error
500 Server Error - Internal server error
Error Response Example
JSON 
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "image": [
      "The image field is required."
    ],
    "quality": [
      "The quality must be between 1 and 100."
    ]
  }
}

Rate Limits & Quotas

API usage is limited based on your subscription plan. Exceeding your plan's limits will result in API requests being rejected until your quota resets or you upgrade your plan.

Monthly Quotas

Your API key is subject to your plan's monthly image optimization quota. You can check your remaining quota using the /api/v1/stats endpoint.

Need More Capacity?

If you need higher limits, consider upgrading to a higher-tier plan on our pricing page.

Ready to optimize your images?

Start building with our powerful API today

Get Started with the API See Pricing Plans