gistfile1.md

Introduction

This document describes the draft API of tinypng.org. The API is a public HTTP service that returns JSON. This document assumes a basic familiarity with performing HTTP requests and parsing JSON responses.

Example usage

To shrink a PNG image, post the data to the shrink endpoint. The response is a JSON message. The initial request must be authorized with HTTP Basic authorization.

Example request

POST /api/shrink HTTP/1.1
Host: api.tinypng.org
Authorization: Basic YXBpOmFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6MDEyMzQ1

The post data should contain the PNG binary. The Authorization header should contain a Base64 digest of the string api:APIKEY, where APIKEY is the API key that has been provided to you.

For example, assuming a test.png file in the current directory and an API key abcdefgh012345:

curl -i --user api:abcdefgh012345 --data-binary @test.png http://api.tinypng.org/api/shrink

Example response when successful

HTTP/1.1 200 OK
Content-Type: application/json

{
  "input": {
    "size": 207565
  },
  "output": {
    "depth": 8,
    "size": 63669,
    "ratio": 0.307,
    "url": "http://api.tinypng.org/api/shrink/out/toab3elfoadgjut7.png"
  }
}

Example response when unsuccessful

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "code": "IncorrectSignature",
  "message": "Does not appear to be a PNG file"
}

Reference

Currently there is only one endpoint. This section describes the possible responses.

Response when successful

If the HTTP status code is 200, the JSON response will contain the following attributes:

input.size
  The size in bytes of the original PNG file.

output.depth
  The bit depth of the shrunk PNG file (currently always 8).

output.size
  The size in bytes of the shrunk PNG file.

output.ratio
  The output size divided by the input size.

output.url
  A URL that points to the shrunk PNG file. The URL will be available
  for at least one hour.

Use the output.url to retrieve the resulting PNG file. The structure of the URL may change in the future, so make sure to use it verbatim from the attribute.

Response when unsuccessful

If the HTTP status code is 4xx or 5xx something has gone wrong during conversion. The JSON response will contain a brief explanation of the reason.

code
  Identifier of the error cause.

message
  Short explanation of the error.

Error codes

The following error codes may be returned. This list may grow in the future.

Unauthorized
  The request was not authorized with a valid API key.

BadMethod
  THe HTTP method was not correct. Only POST requests are supported.

EmptyFile
  The file that was uploaded is empty or no data was posted.

IncorrectSignature
  The file was not recognised as a PNG file. It may be corrupted or it is
  a different file type.

ConversionFailed
  An internal error occurred. If the uploaded file is a valid PNG file,
  try again later.