rethumb - api - image management service

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:

Parse the request and download the original image.
Apply transformations or get data (e.g.: EXIF).
Save the new transformed image or data in our cache.
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:

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

API Documentation

How it works

Entry Point

Parameters

Square Free

Width Free

Height Free

Version Free

Format Paid

Cover Paid

EXIF Paid

Errors

Error codes