API overview

Note: Use cdn.thumbr.it instead of api.thumbr.it if you're on a paid plan and want to use our CDN.

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

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

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.

We will cache the images that you generate for up to 30 days. You can download an unlimited number of times the cached images. The usage limits of each plan only limit the non cached images that you can generate.

If you go over your allocated limit, your images will be watermarked.

Features

Add @2x to the SEO NAME of your images, but take it out to sign the URL. This will allow you to easily request a Retina version of your images from client side code.

To “retinify” automatically all your imgs add this javascript just before you close your body tag:

This way to define an effect is more flexible and direct than doing it into the editor of effects. The effects must be defined into the query arguments zone. In the next table it is mentioned all the arguments we can edit.

Arguments of an inline effect:

Name	Value	Description
grayscale	boolean	The mode of the image. If grayscale equals true, the mode of the image will be grayscale. By default it's false.
hue	integer	It is the number of grades of hue it will be incremented or decremented to all pixels of the image. By default it's 0.
saturation	integer	The percentage increment or decrement of the saturation. The saturation is the intensity of all the colors in the image. By default it's 0
lightness	integer	The percentage increment or decrement of the lightness. The range of possible values is [-100, 100]. By default it's 0
gamma	float	The gamma correction of the image is a exponential operation that it is used to code and decode luminance or tristimulus values in the image. Trought this operation, all pixel values will be elevated to the value of gamma. By default it's 1
contrast	integer	It is the increment / decrement of the image contrast. Contrast is defined as the separation between the darkest and brightest areas of the image. The range of possible values [-127, 127]. By default it's 0
brightness	integer	It is the increment / decrement of the image brightness. The range of possible values [-256, 256]. By default it's 0
r,g,b	array of float	A list of points x, y where the function of the color transformation passes. This list of points have this shape: 'x1, y1, x2, y2, ..., xn, yn', where the x-values must be in order, from 0 to 255. By default it's '0,0,127,127,255,255' In the next example, the color transformation y = 255 - x ('0,255,100,155,255,0') was implement
alpha	string	The image we want as alpha. You can choose between one of these: medium-circle, big-circle, square and alpha-flare. By default, it's none.
q	integer	Quality of the JPEG compression. Valid values are in the range 0 - 100, where 0 is the lowest quality and minimum file size, and 100 is highest quality and maximum file size. By default, it's 95.

You can create an image overlapping different layers on top of each other. Each of these layers can be filtered using all the options described in the previous inline effect section. To specify which options apply to which layer, split the options with the argument compose, which value is the operator used to compose the right layer on top of the left layer.

In the following example we will combine 3 layers, the first layer is the original image (in the URL this part is empty), on top of this layer combined with the operation multiply we will overlay a reddish version of the original image with transparent edges, and we will again overlay the previous image with the frame9. The final query argument to get this multilayer filter is:

Query arguments for multiple layers

Name	Value	Description
compose	string	The possible values of compose are: normal, overlay, screen and multiply. These options blend together two layers using the same algorithm used by Photoshop. The normal mode simply paints the right layer on top of the left layer. The overlay mode gives the image a higher contrast, making dark zones darker and bright zones brighter. The screen mode makes the makes the bottom image brighter. The multiply mode makes the makes the bottom image darker.
src	string	You can change the base image of a layer using the src argument. The possible values are: are: frame1, frame2, ... to frame9, texture 1, texture 2, texture 3, texture 4, texture-2-wo-alpha, texture-3-wo-alpha, texture-4-wo-alpha, scratches and scratches2.

This URL returns a noisy image WIDTH x HEIGHT of a determined density, opacity and color. This feature was created as a service to the community of cssmatic users. The use of this utility is completely free. Its usage will not count against your quota.

Options of whitenoise

Name	Value	Description
WIDTH	integer	The width of the image (between 1 and 2000).
HEIGHT	integer	The height of the image (between 1 and 2000).
OPACITY	integer	The maximum opacity of the image's noise. The range of possible values is [0, 100]. By default it's 15.
DENSITY	integer	The image noise density. The range of possible values is [0, 100]. By default it's 50.
EXTENSION	string	The extension of the image. It can be one of .jpeg, .jpg, .gif or .png.
BACKGROUND	string	The RGBA color of the image's background in hexadecimal format (RRGGBBAA). By default it's FFFFFFFF (solid white color).
NOISE	string	The RGB color of the image's noise in hexadecimal format (RRGGBB). By default it's 000000 (the black color).

You can serve your images from a custom domain (plan "Startup" onwards). To do so you have to make your custom domain a CNAME to "api.thumbr.it" (or "cdn.thumbr.it" if you wish to go through our CDN) in your DNS panel and register your custom domain in your profile.

When you use a custom CNAME you can take out the API key from the URL (the domain name uniquely identifies you), making your URLs shorter. For example, these two URLs are equivalent:

You can make the URLs even shorter and more natural taking our the hmac signature, but in this case you have to restrict the source images to a web directory. For example, if you tie the previous subdomain (img.presspeople.com) to the webdir http://static.presspeople.com/attachment/, the URL http://img.presspeople.com/44ccf523cadf4d4aa4c531eb3de06eda will fetch the image from http://static.presspeople.com/attachment/44ccf523cadf4d4aa4c531eb3de06eda.

You can still use all our powerful arguments, but this time you have to specify them using query arguments.

Thumbr.it provides an editor that you can use in your website. All you have to do is to add the query argument thumbrit-edit=TOKEN (where TOKEN is an ascii string the you can choose freely) to all the images served by Thumbr.it that you want to make editable, and add the code below in the head of your HTML.

If you want to apply the effect selected in an image through the editor to several other images, you can mark these other images with the query argument thumbrit-apply=TOKEN. The effect selected in the editor will be propagated to all the images that share the same token in up to 5 minutes.

You can further customize the Thumbr.it editor. By default, it will let the user select any available effect and it will only show up if the user clicks on the edit image that will show up when you hover with your mouse over the image. You can reduce the set of effects available in the editor, and change on which action you want to show up the editor (on click, hover or have it always visible).

In this example, we only allow the user to select the effects 'none', 'marc', 'brown' and 'barcelona', and make the editor always visible.

Options of the editorThumbrit function

Example:

Select a value for showPanelsOn   click always hover

Number of effects   3 5 10 15 20

* Image courtesy of MorBCN