API Reference

The Tinify API allows you to compress and optimize JPEG and PNG images. It is designed as a REST service. This page describes the raw HTTP API. We also maintain client libraries in various languages that make it very easy to interact with the Tinify API.

The API is hosted at api.tinify.com.

Authentication

To use the API you must provide your API key. You can get an API key by registering with your name and email address. Always keep your API key secret!

Authentication to the API is done with HTTP Basic Auth. All requests require an Authorization header that contains a Base64 digest of the authentication string api:YOUR_API_KEY where YOUR_API_KEY is the key that can be found on your API account page.

All requests must be made over an encrypted HTTPS connection.

Compressing images

You can upload any JPEG or PNG image to the Tinify API to compress it. We will automatically detect the type of image and optimise with the TinyPNG or TinyJPG engine accordingly. Your image is automatically compressed as soon as you upload it.

Example compression request

POST /shrink HTTP/1.1
Host: api.tinify.com

Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

The post data contains the image binary. For example, if you have a file named unoptimized.jpg in the current directory:

curl --dump-header /dev/stdout --user api:YOUR_API_KEY \
     --data-binary @unoptimized.jpg https://api.tinify.com/shrink

Example compression response

HTTP/1.1 201 Created
Compression-Count: 1
Location: https://api.tinify.com/output/2xnsp7jn34e5.jpg
Content-Type: application/json; charset=utf-8

{
  "input": {
    "size": 207565,
    "type": "image/jpeg"
  }
}

The compressed image can be retrieved by using the URL in the Location header.

Example download request

GET /output/2xnsp7jn34e5.jpg HTTP/1.1
Host: api.tinify.com
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

For example, to save the compressed image to a file named optimized.jpg:

curl --dump-header /dev/stdout --silent --user api:YOUR_API_KEY \
     --output optimized.jpg https://api.tinify.com/output/2xnsp7jn34e5.jpg

Example download response

HTTP/1.1 200 OK
Compression-Count: 1
Image-Width: 530
Image-Height: 300
Content-Type: image/jpeg
Content-Length: 46480

[binary data]

Resizing and compressing images

Apart from compressing images, you can also use the Tinify API to create resized versions of your uploaded image. By letting the Tinify API handle resizing you avoid having to write such code yourself, and you only have to upload your image once.

You can also take advantage of our intelligent cropping functionality to create thumbnails that focus on the most visually important areas of your image.

Resizing counts as one additional compression. For example, if you upload a single image and retrieve the optimized version and 2 resized versions this will count as 3 compressions.

You can resize an image by using the URL that was returned in the Location header after compressing. A JSON request body has to be provided together with a Content-Type: application/json header.

Example resize request

GET /output/2xnsp7jn34e5.jpg HTTP/1.1
Host: api.tinify.com
Content-Type: application/json
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

{
  "resize": {
    "method": "fit",
    "width": 150,
    "height": 100
  }
}

For example, to save the resized and compressed image to a file named thumbnail.jpg:

curl --dump-header /dev/stdout --silent --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --output thumbnail.jpg https://api.tinify.com/output/2xnsp7jn34e5.jpg \
     --data '{
       "resize": {
         "method": "fit",
         "width": 150,
         "height": 100
       }
     }'

Example resize response

HTTP/1.1 200 OK
Compression-Count: 2
Image-Width: 150
Image-Height: 85
Content-Type: image/jpeg

[binary data]

Request options

The method describes the way your image will be resized. The following methods are available:

scale
Scales the image down proportionally. You must provide either a target width or a target height, but not both. The scaled image will have exactly the provided width or height.
fit
Scales the image down proportionlly so that it fits within the given dimensions. You must provide both a width and a height. The scaled image will not exceed either of these dimensions.
cover
Scales the image proportionlly and crops it if necessary so that the result has exactly the given dimensions. You must provide both a width and a height. Which parts of the image are cropped away is determined automatically. An intelligent algorithm determines the most important areas and leaves these intact. This feature is experimental. We'd love to have feedback!

If the target dimensions are larger than the original dimensions, the image will not be scaled up. Scaling up is prevented in order to protect the quality of your images.

Uploading to Amazon S3

You can tell the Tinify API to upload compressed images directly to Amazon S3. If you use S3 to host your images this saves you the hassle of downloading images to your server and uploading them to S3 yourself.

You can store an image to S3 by using the URL that was returned in the Location header after compressing. A JSON request body has to be provided together with a Content-Type: application/json header.

Example upload request

POST output/2xnsp7jn34e5.jpg HTTP/1.1
Host: api.tinify.com
Content-Type: application/json
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

{
  "store" : {
    "service": "s3",
    "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "path": "example-bucket/my-images/optimized.jpg"
  }
}

For example, to upload the compressed image to a file named my-images/optimized.jpg in a bucked named example-bucket:

curl --dump-header /dev/stdout --silent --user api:YOUR_API_KEY \
     --header "Content-Type: application/json" \
     --output thumbnail.jpg https://api.tinify.com/output/2xnsp7jn34e5.jpg \
     --data '{
       "store" : {
         "service": "s3",
         "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
         "aws_secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
         "path": "example-bucket/my-images/optimized.jpg"
       }
     }'

Example upload response

HTTP/1.1 200 OK
Compression-Count: 3
Image-Width: 530
Image-Height: 300

Request options

You need to provide the following options in order to store an image on Amazon S3:

service
Must be s3 as currently only Amazon S3 is supported.
aws_access_key_id
aws_secret_access_key
Your AWS access key ID and secret access key. These are the credentials to an Amazon AWS user account. Find out how to obtain them in Amazon's documentation. The user must have the correct permissions, see below for details.
path
The path at which you want to store the image including the bucket name. The path must be supplied in the following format: <bucket>/<path>/<filename>.

The user that corresponds to your AWS access key ID must have the GetBucketLocation permission on the bucket and the PutObject and PutObjectAcl permissions on the objects you intend to create.

If you want to create a user with limited access specifically for the Tinify API, you can use the following example policy as a starting point:

{
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation"],
      "Resource": ["arn:aws:s3:::example-bucket"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl"],
      "Resource": ["arn:aws:s3:::example-bucket/*"]
    }
  ]
}

Error handling

The Tinify API uses HTTP status codes to indicate success or failure. Status codes in the 2xx range indicate success. Status codes in the 4xx range indicate there was a problem with your request. Status codes in the 5xx indicate a temporary problem with the Tinify API.

In case an error occurs, the HTTP body will contain the error details formatted as JSON. The message will contain a short human readable description.

Example error response

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
  "error": "Unauthorized",
  "message": "Credentials are invalid"
}

Try TinyPNG with a new browser

TinyPNG is created for modern browers with HTML5 & CSS3 support. We have not tried it out in other browsers. The site may work, or it may not. If you see this message you may want to try a different browser!