Documentation

Description

With our API you can serve responsive images, create thumbnails, add filters, crop, and modify in several ways your images, on the fly and without the need to edit your original image files.

http://api.thumbr.io/HMAC TOKEN/API KEY/URL/DIMENSIONOPTIONS/SEO NAME.EXTENSION

Note: Upgrade to a paid plan to use our CDN. Make your domain a CNAME to cdn.thumbr.io.

Real examples:

      
        http://api.thumbr.io/45e5a5c43c86ba4073c174caff1dee45/VyEXO3VGSPYpIujFxmB-/https%3A//www.google.com/logos/2012/javelin-2012-hp.jpg/300x200-ehipster/thumb.jpg
http://api.thumbr.io/a8701fed24a905990994efc532417f8a/VyEXO3VGSPYpIujFxmB-/static.panoramio.com/photos/medium/65201270.jpg/400x400c-esummer-eframe1/thumb.png

Url parts

Name Value Description
HMAC TOKEN string HMAC (MD5) of the full URL taking out the HMAC TOKEN itself. The key is your SECRET_KEY in your profile page.
API KEY string Your API_KEY in your profile page.
URL string The URL of the object that you want to resize (it can be an image, pdf, doc, ppt, xls).
DIMENSION string* The dimension of the thumbnail (in pixels) [* see Dimensions]
OPTIONS string* Inline options to apply to your thumbnail. [* see Inline Options].
SEO NAME string Whatever name you fancy (using only a-z A-Z 0-9). We ignore this name (except if it ends with @2x).
EXTENSION string* The format of the thumbnail. It can be one of 'png', 'jpg' or 'gif'.

You can previsualize all effects and some options in the Quick Start page. Check it out!

Dimensions

WIDTH x HEIGHT is the simplest, but not the only way to specify the size of the output image. You can also use:

Syntax Description
WIDTH x HEIGHT default. Maximum WIDTH and HEIGHT of the output image. The image will be resized keeping its aspect until its width is equal to WIDTH and its height is less or equal than HEIGHT (or viceversa).
WIDTH x Maximum WIDTH of the output image. The height will be choosen to keep the original aspect ratio of the image.
x HEIGHT Maximum HEIGHT of the output image. The width will be choosen to keep the original aspect ratio of the image.
SIZE Equivalent to SIZE x SIZE.
WIDTH x HEIGHT ^ minimum WIDTH and HEIGHT of the output image. The image will be resized keeping its aspect until its width is equal to WIDTH and its height is greater or equal than HEIGHT (or viceversa). This mode is implied when you use the CROP option.
< WIDTH x HEIGHT the image will only be enlarged.
> WIDTH x HEIGHT the image will only be shrinked.

After define the dimensions we can apply two optional options: CROP and FILL.

Name Value Description
CROP string* Put here a "c", "t", "b", "l", "r" or "s" to crop the thumbnail. The final image will be WIDTH x HEIGHT pixels and keep its aspect ratio. You can keep the center of the image, the top, bottom, left, right or make a "smart" crop where we will try to keep all the faces from the photo in the final crop. You can combine several flags, like in 300x300tr.
FILL f This option fills the background image with a color (transparent by default). If you want to choose another color, you can define it in the query argument bg.
This option indicates the maximum size of the image. If you make use of a crop option, this flag will indicate us where the image have to be located. For example, if we use the crop l, the image will be at the left side.

example image
size=90x150tf
example image
size=90x150cf
example image
size=90x150bf
example image
size=150x90lf
example image
size=150x90cf
example image
size=150x90rf

Inline options

We can apply all of these optional options:

Name Value Description
EFFECTS -e <effect> Optional. Apply one or several effects to the thumbnail.
The available effects are:
barcelona, brown, bw, canary, cool, fire, fun, hipster, love, marc, nyc, old, sepia, summer, sunshine, tales, thames, trendy and water, frame1, frame2, ..., frame9 and lightleak. Preview them here.

For example: -enyc-esummer-eframe1
ROTATE -r <angle> Angle of rotation applied to the image (from 0 to 360).
For example: -r90
MIRROR -m If true, thumbnail will be flipped horizontally.
Example: -m

Query arguments

In addition to the above url options passed in the image call, you can pass options to the image through query arguments. This is very useful when you want to use a short URL, for example using custom CNAMEs.

Name Value Description
size string The maximum width and height of the thumbnail (in pixels) [* see Dimensions].
Example: &size=400x300c
ext string The format of the thumbnail. It can be one of 'png', 'jpg' or 'gif'.
Example: &ext=png
d boolean Force to download the thumbnail.
Example: &d=1
angle integer Angle of rotation applied to the image (from 0 to 360).
Example: &angle=180
example image
angle=0
example image
angle=180
mirror boolean If true, thumbnail will be flipped horizontally.
Example: &mirror=1
example image
mirror=0
example image
mirror=1
effects string A list of effects that it will be applied to the image. It must be separated by commas.
Example: &effects=nyc,cool,frame6
example image
effects=nyc,cool,frame6
watermark string The URL of the image you want to use as a watermark [* see watermark].
Example: &watermark=thumbr.io/img/thumbrio-white.png
example image
watermark=thumbr.io/img...
wmin_w,
wmin_h
integer The minimum size required to use your custom watermark image over the requested image.
wmin_w = minimum width | wmin_h = minimum height
Example: &wmin_w=150
example image
wmin_w=150 (image size=150x)
example image
wmin_w=150 (image size=200x)

Example: &wmin_h=150
example image
wmin_h=150 (image size=x150)
example image
wmin_h=150 (image size=x200)
dpr float dpr means Device Pixel Ratio. It's a multiplier to the size of the image. If the requested size multiplied by dpr is larger than the original image, we will serve the original image (we will not artificially enlarge the original image with this option). If the dpr is > 1 we will lower the quality of JPEG images. This loss of quality is imperceptible to the human eye at higher resolutions, and it greatly helps compressing the image.
Note: dpr=2 is virtually identical to enabling the @2x modifier in the filename.
Example: &dpr=1.5
example image
dpr=1.5
lossy boolean We will change PNG files to use a palette of colors. The paletted image will respect transparent and semi transparent pixels, and usually it will be smaller and of almost identical quality. We use pngquant behind the scenes. Important: small images will be compressed inmediatly on the first request, but bigger images will be compressed on a background queue. The first time we will quickly serve you a regular, lossless PNG, and when we're done compressing the image we will automatically invalidate the cache and serve the lossy (highly compressed) image. This process usually takes a few seconds.

Example: &lossy=1
example image
lossy=1
rect string Selects a rectangle shaped zone of the source image before resizing. The expected value for this argument is "x, y, width, height". The coordinate (x, y) represents the left upper corner; width and height are the sides length of the rectangle.
Example: &rect=50,90,200,190
example image
rect=50,90,200,190
alpha=ellipse string We will return the image to the requested size and cropped elliptical
Example: &alpha=ellipse
example image
alpha=ellipse
pad string This option pads the image requested with a background color (transparent by default). If you want to choose another color, you can define it in the query argument bg.
If the image is requested without a specified size, padding will add to the dimension of the image. Otherwise, if you specific an image size the result is the sum of the scaled image and the selected padding pixels.
Example: &pad=10,20,10,20
example image
size=160x160
example image
size=160x160&pad=10,10,10,10
example image
size=160x160c&pad=10,10,10,10
example image
size=160x160c&pad=10,0,0,20
bg string Set a background color expressed in hexadecimal. This option only should be declared when we use the fill (f) option in size, or padding (pad) option in query arguments. By default, the background color is ffffff00 (transparent).
Example: &bg=aa00c2ff
example image
bg=00000000&size=150cf
example image
bg=000000ff&size=150tf

Usage limits

We will cache the images that you generate for up to 30 days. You can download an unlimited number of times the cached images.