Free Trial
10 days, no credit_card

API Documentation

This page describes all the requests avaible in the current version: v1 online since 26/Jul/2012 .

How it works

Our API flow after receiving a new request:

  1. Parse the request and download the original image.
  2. Apply transformations or get data (e.g.: EXIF).
  3. Save the new transformed image or data in our cache.
  4. Send new transformed image or JSON document.

After the first request we will always send the cached version, even if the original image is no longer online. To force an image to be processed again just add the version parameter to the request URL (check docs bellow on how to do that).

Entry Point

All requests start with http://api.rethumb.com/v1/ or https://api.rethumb.com/v1/ and have the following format:


http://api.rethumb.com/v1/<parameter_1>/<value_1>/<image_url>
http://api.rethumb.com/v1/<parameter_1>/<value_1>/<parameter_2>/<value_2>/<image_url>

The request must end with the URL of the image to process (HTTP or HTTPS). Support for JPEG, GIF, PNG, TIFF or WEBP files.

Parameters

The following parameters can be used in any order.


Square Free

This will return a centered square thumbnail from the original image, cropping when needed.


Value

square — Width and height of the thumbnail in pixels (height and width will be equal).


Examples
http://api.rethumb.com/v1/square/175/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/square/175/version/xc98/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/square/175/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/square/175/version/xc98/http://images.rethumb.com/image_coimbra_600x600.jpg

Return

This will return a HTTP status code 200 with an image in the same format of the original. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Width Free

This will return a thumbnail of the given width (image ratio is kept).


Value

width — Width of the thumbnail in pixels.


Examples
http://api.rethumb.com/v1/width/250/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/250/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/width/250/version/xc38/http://images.rethumb.com/image_coimbra_600x600.jpg

Return

This will return a HTTP status code 200 with an image in the same format of the original. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Height Free

This will return a thumbnail of the given height (image ratio is kept).


Value

height — Height of the thumbnail in pixels.


Examples
http://api.rethumb.com/v1/height/250/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/height/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/height/250/http://images.rethumb.com/image_coimbra_600x600.jpg
http://api.rethumb.com/v1/height/250/version/xc38/http://images.rethumb.com/image_coimbra_600x600.jpg

Return

This will return a HTTP status code 200 with an image in the same format of the original. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Version Free

An alphanumeric value that represents the version of the image. When changed the API will process the image again.


Value

version — An alphanumeric value that represents the version of the image. When changed the API will process the image again.


Examples
http://api.rethumb.com/v1/width/100/height/250/version/xc38/http://factor45.org/images/beach.jpg
http://api.rethumb.com/v1/width/100/height/250/version/00001/http://images.rethumb.com/image_coimbra_600x600.jpg

Return

This will return a HTTP status code 200 with an image in the same format of the original. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Format Paid

This will return an image converted to the given format. This is a paid feature, you'll need to subscribe to a plan first.


Value

format — The output image format. Valid values are:

  • jpg/jpeg
  • gif
  • png
  • tif/tiff
  • webp

This parameter must be used with other image transformation like square, width or height.


Examples
http://api.rethumb.com/v1/height/250/format/jpg/http://images.rethumb.com/image_coimbra_300x300.jpg
http://api.rethumb.com/v1/height/250/format/gif/http://images.rethumb.com/image_coimbra_300x300.jpg
http://api.rethumb.com/v1/square/250/format/png/http://images.rethumb.com/image_coimbra_300x300.jpg
http://api.rethumb.com/v1/square/250/format/webp/http://images.rethumb.com/image_coimbra_300x300.jpg

Return

This will return a HTTP status code 200 with an image in the given format. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Cover Paid

This will return an image upscaled/downscale and croped to fit the given dimensions. This is a paid feature, you'll need to subscribe to a plan first.


Value

cover — Dimensions of the thumbnail in a WEIGHTxHEIGHT format, example: 600x400. If needed, this operation will crop the image.


Examples
http://api.rethumb.com/v1/cover/150x50/http://images.rethumb.com/image_coimbra_300x300.jpg
http://api.rethumb.com/v1/cover/400x150/http://images.rethumb.com/image_coimbra_300x300.jpg
http://api.rethumb.com/v1/cover/400x150/format/png/http://images.rethumb.com/image_coimbra_300x300.jpg

Return

This will return a HTTP status code 200 with an image in the same format of the original. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

EXIF Paid

This will return a JSON document with the EXIF info of the image. This is a paid feature, you'll need to subscribe to a plan first.


Value

exif — EXIF Tag ID to return a specifc value or 'all' to get all EXIF info available.


Examples
http://api.rethumb.com/v1/exif/110/http://images.rethumb.com/image_exif_1.jpg
http://api.rethumb.com/v1/exif/all/http://images.rethumb.com/image_exif_1.jpg

Return

This will return a HTTP status code 200 with a JSON document. In case of error it will return a HTTP status code 400, a PNG image and a HTTP header (rethumb-error-message) with the error code and message.

Errors

API requests that result in a error will return:

  1. HTTP Status code 400;
  2. PNG image with a error message and error code;
  3. Custom HTTP header with an error message and error code: rethumb-error-message.

Error Example:

http://api.rethumb.com/v1/height/9999//http://factor45.org/images/beach.jpg

Custom HTTP header:

rethumb-error-message: "Height must be less than 513. (#503)"

Error codes

The following list shows all errors that the API return.

Code Error
#101Datbase error, repeat the request again.
#102Datbase error, repeat the request again.
#103Datbase error, repeat the request again.
#201Storage error, repeat the request again.
#202Storage error, repeat the request again.
#203Storage error, repeat the request again.
#301Version parameter invalid length, value is too long (Max: 16 characters).
#302Version parameter invalid value, value must be alphanumeric: [A-z0-9].
#401Image is too large, try with a smaller image (Max: 512 kB for free accounts).
#402Image MIME type not found, invalid image.
#403Image MIME type not supported, this service doesn't support the found MIME type.
#404Error processing image, generic image error, try again or with a diferent image.
#501Height parameter is not numeric.
#502Height parameter is not a positive number.
#503Height parameter is larger than the max allowed (in free: 512).
#601Width parameter in percent must be numeric.
#602Width parameter in percent must be between 1 and 99.
#603Width parameter is not numeric.
#604Width parameter is not a positive number.
#605Width parameter is larger than the max allowed (in free: 512).
#701Square parameter is not numeric.
#702Square parameter is not a positive number.
#703Square parameter is larger than the max allowed (in free: 512).
#801Width parameter is not numeric.
#802Width parameter is not a positive number.
#803Width parameter is larger than the max allowed (in free: 512).
#804Height parameter is not numeric.
#805Height parameter is not a positive number.
#806Height parameter is larger than the max allowed (in free: 512).
#901EXIF tag not found in image.
#902EXIF invalid tag.
#903EXIF info not found in image.
#904Invalid MIME type for EXIF info.
#1001Error downloading image, try again or use a different URL.
#1101URL not found in parameters.
#1102Parameters duplicated, remove one.
#1103Invalid parameters found in request.
#1104URL parameter must start with http:// or https://.
#1105Too many parameters.
#1106Can't mix two types of parameters.
#1107Invalid parameter.
#1108Invalid parameter.
#1109Invalid context for parameter.
#1110Invalid URL: can't use api.rethumb.com as source.
#1201Too many requests, contact [email protected]
#1202Image is already processed, try again.
#1203Generic error, try again.
#1204Image is being processed, try again.
#1205Image is being processed, try again.
#1206Error processing image, please try again.
#1301This feature is not available in a free plan.
#1401System is down for maintenance. Try again shortly.
#1501Invalid HTTP method. Try again using GET.
#1601Invalid image format. Valid values: jpg, gif, png, tiff or webp.
#1701Invalid parameter. Check if the cover parameter is in the following format: 612x800.
#1702Cover width must be numeric.
#1703Cover width must be positive.
#1704Cover width is larger than the max allowed (in free: 512).
#1705Cover height must be numeric.
#1706Cover height must be positive.
#1707Cover height is larger than the max allowed (in free: 512).