Operations

These are all available image processing operations. To use them, append the specified parameters to the url as query parameters. You may use none, one, several, or all of these operations at the same time. When parameters are omitted, the operation is either skipped or executed with a default value.

General

Source image URL

Basic usage

To specify the source image URL, just append it to https://tiny.pictures/api/demo?source=.

If there are fancy characters in your URL (especially if there is a query string in it), URL-escape the URL before appending (that is, use JavaScript's encodeURIComponent function).

http://your.domain/path/to/image.jpg

becomes

https://tiny.pictures/api/demo?source=http://your.domain/path/to/image.jpg

or URL-encoded

https://tiny.pictures/api/demo/?source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg

Named source usage

In order to create shorter and easier to read URLs, you can create a "named source".

For this example, let's assume the user demo has created a named source main that acts as a shortcut to the publicly available web folder https://tiny.pictures.

Now, all images in the web folder become accessible at

https://tiny.pictures/api/demo/main

This only works for source image URLs that do no include a query string.

https://tiny.pictures/example1.jpg

becomes

https://tiny.pictures/api/demo/main/example1.jpg

You may want to use our JavaScript library for convenience.
The demo part of the URL means that you are using our usage-limited demo account. Please register to receive an API URL on a custom subdomain just for yourself.

Metadata

The following metadata is sent in HTTP headers of the resized image.

Cache-Control

The original header set by the source server is passed on to give the image owner full control over caching.

This is the period that tiny.pictures' CDN cache as well as other cache servers on the internet (e. g. your users' internet service providers) will keep a copy of the output image without the need to reload or recalculate the source image.

tiny.pictures' caching qualifies for the DMCA's 512(b) caching "safe harbor" and is considered fair use. If you do not want your content to be cached by tiny.pictures or other cache servers, set an appropriate Cache-Control header.

You can leverage the full potential of our CDN by setting the maximum age on your source server as high as possible. Use different URLs for different content instead of updating the content of the same URL. The maximum age should be at least 10 days (864,000 seconds).
ETag
The original header set by the source server is passed on to enable browser caching.
Last-Modified
The original header set by the source server is passed on to enable browser caching.
X-TinyPictures-Original-Url
The source image URL that we parsed from your request. You can use this for debugging.
X-TinyPictures-Original-Format
Image file format, e. g. jpeg, png, webp, gif, svg.
X-TinyPictures-Original-Width
Width in pixels.
X-TinyPictures-Original-Height
Height in pixels.
X-TinyPictures-Redirect-Reason
Reason why your request got redirected to the original source image URL. This is most likely because you tried to get an image from a local domain like e. g. localhost or project.local.

Resize

This operation resizes a JPEG, PNG, WebP, TIFF, GIF or SVG image file to fit into or fill the given dimensions (see resizeType parameter below). It does not try to enlarge an image if the source file is smaller. Image processing is done on the fly in a streaming manner. Use this if you don't want to bother resizing images yourself or if you need images in varying dimensions.

Example

https://tiny.pictures/api/demo/main/example6.jpg?width=200&height=200

Original image

Natural size is 1000 x 667 pixels at 100 % quality.

Output image

Natural size is 526 x 351 pixels at 80 % quality.

Parameters

width (number)
Optional. Default is null. Number of pixels wide the resized image should be, between 1 and 16383. Use null to automatically adjust the width to height while preserving aspect ratio.
height (number)
Optional. Default is null. Number of pixels high the resized image should be, between 1 and 16383. Use null or omit to automatically adjust the height to width while preserving aspect ratio.
enlarge (boolean)
Optional. Default is false. Set to true to enable upscaling. This means the output image size may be greater than the original image's size. Enlarged images are automatically sharpened. Use with caution because this unnecessarily blows up file size and may result in pixelated images.
resizeType (string)
Optional. Default is fit. If both width and height are set (see above), there are several types of resize operations. Possible values are fit, fill, and ignore.
fit returns an image of the maximum dimensions that fit into the given dimensions. It preserves aspect ratio of both the image's content and the image file.

fill returns an image of the given dimensions. If the aspect ratio of the given dimensions differs from that of the source image, the image is cropped (see gravity parameter below).

ignore returns an image of the given dimensions. It ignores aspect ratio. The output image may appear stretched or shrunk in one dimension.

gravity (string)
Optional. Default is center. Can only be used with resizeType fill. Sets the cropping strategy.
Compass points set the image's focus to an edge or corner. Possible values are north, northeast, east, southeast, south, southwest, west, and nothwest. The following example uses gravity southeast for the lower right corner.

A comma-separated pair of numbers describes the focal point of the image. Each value describes the distance from the top left corner of the image as a value between 0.0 and 1.0. The following two examples use a gravity of 0.46,0.34 (46 % from left and 34 % from the top) to always focus the top of the larger palm tree.


Use our focal point demo to select the best focal point for your image.

entropy sets the image's focus to the region with the highest Shannon entropy.

attention sets the image's focus to the region with the highest luminance frequency, color saturation and presence of skin tones (face recognition).

Format

Sets the output image format.

Example

https://tiny.pictures/api/demo/main/example7.png?format=jpeg&width=526

Original image

PNG format.

Output image

JPG format.

Parameters

format (string)
Optional. Default is auto. Valid values are auto, jpeg, png, and webp. You probably want to use the auto setting (or simply omit this parameter).
auto automatically determines the optimal image format. PNG and WebP is kept as is. GIF is converted to PNG. All other formats are converted to WebP if the user's browser supports it or JPEG otherwise.

Optimize

Lossless file size optimization for PNG output. This may save a considerable part of the file size, especially if it's possible for the algorithm to reduce the amount of colors in the palette, e. g. for screen shots or grayscale images.

Due to the nature of such an operation, it takes a huge amount of computing power and therefore the first call is slower than without optimization. However, since tiny.pictures is equipped with a CDN, setting a reasonable cache period enables super-fast download times for subsequent calls.

This operation is lossless. Use it anytime you can.

Example

https://tiny.pictures/api/demo/main/example1.jpg?grayscale=true&format=png&optimize=true&width=526

Original image

Without optimization.

Output image

With optimization.

Parameters

optimize (boolean)
Optional. Default is false. Can be true or false.

Quality

Sets the output quality in percent for lossy image formats like JPEG and WebP.

Example

https://tiny.pictures/api/demo/main/example2.jpg?quality=50&width=526

Original image

100 % quality.

Output image

50 % quality.

Parameters

quality (number)
Optional. Default is 80. Can be a number between 1 and 100.
This is a powerful option that lets you significantly crunch the file size (see the example above). However, please keep in mind that our default quality is 80 %. Set it to a value between 95 and 100 % for images that have to be crystal clear and when bandwidth is not an issue.

Trim

Remove pixels from the image's edges which are similar to the image's top left pixel.

Example

https://tiny.pictures/api/demo/main/example3.jpg?trim=20&width=526

Original image

Natural size is 1,000 x 667 pixels and 26,724 bytes.

Output image

Natural size is 1,000 x 573 pixels and 26,014 bytes.

Parameters

trim (number | boolean)
Optional. Default is no operation. Sets the tolerance used to determine similarity between each pixel and the top left one. Can be a number between 1 and 50. When set to true or empty string, a value of 10 is used.

Blur

Applies a visual effect as if seeing the image through a translucent screen. Can be used to reduce image noise and image detail or to create fast-loading "preview" images during page load.

Example

https://tiny.pictures/api/demo/main/example4.jpg?blur=10&width=526

Original image
Output image

Parameters

blur (number | boolean)
Optional. Default is no operation. Sets the sigma value for the Gaussian blur. Can be a number between 0.3 and 100. When set to true or empty string, a mild and fast blur is applied.

Grayscale

Reduces the image's colors to a set of 256 shades of gray and dismisses all but one color channel (+ the alpha channel if present).

Example

https://tiny.pictures/api/demo/main/example5.jpg?grayscale=true&width=526

Original image
Output image

Parameters

grayscale (boolean)
Optional. Default is no operation. When set to true or empty string, the operation is applied.

Rotate

Rotate the image by an angle or based on EXIF data.

Example

https://tiny.pictures/api/demo/main/example1.jpg?rotate=90&width=526

Original image
Output image

Parameters

rotate (number | boolean)
Optional. Default is no operation. When set to 90, 180, or 270 the image is rotated by the given degrees. When set to true or empty string, the image is rotated according to the EXIF Orientation tag.

Flip

Mirror the image at its horizontal axis.

Example

https://tiny.pictures/api/demo/main/example2.jpg?flip=true&width=526

Original image
Output image

Parameters

flip (boolean)
Optional. Default is no operation. When set to true or empty string, the operation is applied.

Flop

Mirror the image at its vertical axis.

Example

https://tiny.pictures/api/demo/main/example3.jpg?flop=true&width=526

Original image
Output image

Parameters

flop (boolean)
Optional. Default is no operation. When set to true or empty string, the operation is applied.

Invert

Negate the image's colors.

Example

https://tiny.pictures/api/demo/main/example4.jpg?invert=true&width=526

Original image
Output image

Parameters

invert (boolean)
Optional. Default is no operation. When set to true or empty string, the operation is applied.

Combinations

You can combine any number of operations with each other.

Example

https://tiny.pictures/api/demo/main/example5.jpg?width=300&height=300&flip=true&grayscale=true&quality=50

Original image
Output image