The TweenPics API is URL-based and every URL is structured as follows:
<manipulation>is a list of one or more transformations separated by the character
<authentication>is an identifier that allows the use of any source image regardless of its domain (see the documentation about authentication for more information)
<source image>is the URL of the image to manipulate (only
https:protocols are supported at the moment)
Here are two basic examples:
http://mydomain.com/myimage.pngto a width of 450 pixels while preserving its aspect ratio
http://mydomain.com/myimage.pngto a width of 300 pixels while preserving its aspect ratio, on behalf of the client identified by the authentication identifier
Whenever something goes wrong, TweenPics will issue an HTTP error with a sensible status code and a short explanation in plain text as a body.
TweenPics will error when:
- there is a syntax error in the manipulation expression
- the authentication identifier is invalid
- the URL of the source image is not well-formed or its protocol is not supported
- the domain of the source image is not registered (see the documentation about domain name registration)
- the source image is unreachable (ie. the
GETrequest to retrieve it resulted in an HTTP error)
- the source image is of an unsupported format (only JPEG, PNG and WebP are currently supported)
- the source image, the output image or any intermediate image created while processing the transformations doesn't respect the internal pixel and/or byte size limits of TweenPics (ie. one of the images has a dimension of zero or is "too big")
- a transformation ends up cropping outside of the image (for instance when attempting to crop 500 pixels out of an image that is only 200 pixels wide)
Whenever an image does not show in your web page, be sure to check the network tab of your favorite dev tool for those red-colored lines indicative of a network error.
As seen previously, a manipulation is a list of transformations that are chained together using the character
/. There is no limit to the number of transformations you can chain, save for the limit in size of a URL as enforced by your browser. No matter how complex the manipulation, TweenPics will optimize it for speed and accuracy on the fly.
Transformations all have the same structure:
<name>is the name of the transformation
<parameters>is an expression specifying the parameters for the transformation
resize=400will resize the image to 400 pixels in width while conserving the source image aspect ratio
resize=640x480will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio
Types of parameters
The TweenPics API strives to be as consistent as possible and, as such, transformations will use the same format for parameters that represent the same underlying concept.
Tweenpics numbers can be JSON-encoded number literals or expressions that, when computed, result in an actual number. Expressions are embedded in parenthesis. Operators
/ are supported for additions, subtractions, multiplications and divisions respectively. Classic algebraic precedence is respected and parenthesis can be used to circumvent it.
(5*(7+2)/3) are all valid numbers.
TweenPics lengths are equivalent to CSS length values. They consist of a number eventually followed by a unit specifier:
- when no unit is specified, the length is in pixels, for instance
50is a pixel length that can be read as "50 pixels"
- with the unit specifier "s", the length is a scale, for instance
(1/3)sis a scale length that can be read as "one third"
- with the unit specifier "p", the length is a percentage, for instance
4.5pis a percentage length representing "4.5%"
Coordinates represent a point in an image, specified as a couple of positive lengths separated by the character
- the first length is the coordinate along the x-axis (following the width of the image)
- the second length is the coordinate along the y-axis (following the height of the image)
TweenPics uses the same coordinate system as CSS: zero-based, left-to-right and top-to-bottom.
If we take the example of an image that is 640 pixel-wide and 480 pixel-high:
0x0points to the top-left corner pixel
639x479points to the bottom-right corner pixel.
It is perfectly fine to mix lengths of different units in the same coordinates. For instance, in the context of yet another 640 per 480 sample image, coordinates
100x50p actually translate to
A size represents a 2D area, specified as a couple of strictly positive lengths separated by the character
- the first length is the width of the area
- the second length is the height of the area
640x480 is 640 pixel-wide per 480 pixel-high.
It is possible to omit one of the dimensions using the character
-. In that case, TweenPics will automatically compute the missing dimension so that the size respects the aspect ratio of the source image. For instance, if the source image is 640 pixel-wide per 480 pixel-high, then sizes
-x240 are both equivalent to
As a shortcut, it is possible to omit the height by specifying just a width. For instance, the size
320 is equivalent to
As for coordinates, it is perfectly fine to mix lengths of different units in the same size. As an example, the size
10px150 is a perfectly valid.
A crop size is a size where omitted dimensions are assumed to be the same as the input image.
320x-are equivalent to
-x240is equivalent to
A ratio represents the proportional relationship between a width and a height. It is specified as a couple of strictly positive numbers separated by the character
- the first number is the number of length units contained in the width
- the second number is the number of length units contained in the height
For instance, the ratio
9:3 indicates that the width is 9-units long while the height is 3-units long. In terms of proportions, the width is (9/3=)3 times longer than the height.
Transformations behave differently depending on which point in the image is the main focus. TweenPics will do its best to keep this focus point as central as possible within the transformed image.
By default, the focus point is in the middle of the image but you can change its coordinates by using the
The biggest extractable area of the image that has the focus point as its center is called the focus window. By default, since the focus point is right in the middle of the image, the focus window is actually the image itself.
Here is, delimited in red, the focus window of a 300 pixel-wide per 188 pixel-high cat face with the focus point set at
When adding a transformation to the chain, the parameters given are interpreted as if previous transformations had already been performed (ie. as if the source image was the result of the previous transformations).
resize=340/resize=50pwill result in an image that is 170 pixel-wide
resize=50p/focus=20x10will put the focus point at coordinates
40x20of the source image
Since TweenPics will optimize the manipulation, be aware that a transformation may shadow what came before it. For instance
resize=50p/resize=340 will result in an image that is 340 pixel-wide: TweenPics will simply ignore the first resize.
contain behaves like the CSS background size "contain". It will resize the image so that it completely fits inside the target area while conserving the original aspect ratio. The resulting image will be smaller than a target size which aspect ratio is not the same as the aspect ratio of the input.
For instance, applying
contain=150x100 to our beloved face of a cat will result in the following 150x94 image:
A conditional version of contain that will be applied only when one of the given lengths is larger than the corresponding input image dimension.
A conditional version of contain that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
cover behaves like the CSS background size "cover". It will resize the image so that it completely fills the target area while conserving the original aspect ratio. If some parts of the image end up outside of the covered area, they are cropped.
cover=100x100 of a 300x188 image would first scale the image down to a height of 100 pixels and then crop along the x-axis as demonstrated below:
cover will use the focus point as a guide and will crop the image so that the focus point is as central as possible in the resulting image. For instance,
focus=85x85/cover=100x100 will behave as follows:
When a ratio is provided, cover will extract the biggest possible area contained within the focus window that satisfies the ratio and is centered on the focus point. For instance,
focus=85x85/cover=2:1 will behave as follows:
A conditional version of cover that will be applied only when one of the given lengths is larger than the corresponding input image dimension.
A conditional version of cover that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
crop will extract a zone from the image which size is the given crop size. If no coordinates are given, the focus point will be used as a guide to determine where to start the extraction. If coordinates are given, they will be used to determine the top-left pixel from which to start the extraction.
Here are two examples:
focus will set the focus point coordinates, incidentally changing the focus window. It doesn't modify the output image in any way but will change the behavior of further transformations that take the focus point into account (namely cover, crop and resize).
Specifies the output format. Only the last format in the manipulation expression is taken into account. By default, TweenPics will "smart-guess" the best format for the browser currently requesting the image but you can use format to override this behavior.
Available formats are:
jpeg[-<quality>]for jpeg where quality is an integer between 1 and 100 (default 70)
webp[-<quality>]for webp where quality is an integer between 1 and 100 (default 70)
Alias of contain-max.
Alias of contain-min.
resize will resize the image to the specified size. If only one length is provided, the other dimension will be determined so as to respect the aspect ratio of the input image. If both lengths are provided, the aspect ratio may not be respected.
Here are three resize operations on the same source image:
If a ratio is provided, the focus window will be resized so that it stays as close as possible to its current surface (i.e number of pixels) while respecting the given aspect ratio.
focus=85x85/resize=4:3 will behave as follows:
The 170x170 focus window was resized to a 196x147 image (respecting the 4:3 ratio). The initial surface was (170x170=) 28,900 pixels. The final surface is (196x147=) 28,812 pixels.
A conditional version of resize that will applied only when one of the given lengths is larger than the corresponding input image dimension.
A conditional version of resize that will be applied only when one of the given lengths is smaller than the corresponding input image dimension.
step will round the image width and/or height to the closest multiples of the corresponding pixel lengths. If only one length is provided, the other dimension will be determined so as to respect the aspect ratio of the input image. If both lengths are provided, the aspect ratio may not be respected.
Let's take the example of a 206 pixel-wide per 103 pixel-high image (aspect ratio 2:1):
step=10will resize the width to 210 and result in a 210 per 105 output, respecting the 2:1 aspect ratio
step=-x10will resize the height to 100 and result in a 200 per 100 output, respecting the 2:1 aspect ratio
step=10x10will resize both the width to 210 and the height to 100 thus not respecting the 2:1 aspect ratio