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

There are two ways to pass the source image URL to tiny.pictures. By named sources (recommended) and by the source parameter (paid plans only).

Named sources (recommended)

In order to create short and easy to read URLs, you can create a "named source" on the Sources tab of your dashboard, which is available after registration.

Named sources are shortcuts from your tiny.pictures sub domain to web folders in which your images are located. You can have as many of them as you like.

This method only works for source image URLs that do not include a query string, because the query string is used to describe the image operations that should be applied.

For this example, let's assume the user demo 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/<imagePath>.

For example,

https://tiny.pictures/example1.jpg

becomes

https://demo.tiny.pictures/main/example1.jpg
You may want to use our JavaScript or PHP library for convenience.

Source parameter (paid plans only)

You may also transform arbitrary public images on the internet, even if they are not hosted at a named source of yours. This feature is only available in some paid plans (see Pricing for details).

To specify the source image URL, just append it like this: 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 (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://demo.tiny.pictures/?source=http%3A%2F%2Fyour.domain%2Fpath%2Fto%2Fimage.jpg

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) may keep a copy of the output image without the need to reload or recalculate the source image.

You can override the values of the origin server by setting a minimum maxAge on the Sources tab of your dashboard, which is available after registration.

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-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.
X-TinyPictures-Original-Format
Image file format, e. g. jpeg, png, webp, gif, svg. Only sent if the metadata query parameter is set.
X-TinyPictures-Original-Width
Width of the original image in pixels. Only sent if the metadata query parameter is set.
X-TinyPictures-Original-Height
Height of the original image in pixels. Only sent if the metadata query parameter is set.

Authentication

You may also use image sources that are protected by HTTP Basic Authentication. This feature is primarily used to protect your original images when using overlays to watermark your images.

You can set this up on the Sources tab of your dashboard. Please note that, for technical reasons, we have to store your password in plain text. Please choose a unique password you do not use anywhere else.

Parameters

User name (string)
User name to be used in the preemptive HTTP Basic Authentication request.
Password (string)
Password to be used in the preemptive HTTP Basic Authentication request.

Overlay

For each named source, you can define a mandatory image overlay, most commonly used as a watermark. The overlay image may have transparent or partially transparent areas in it (e. g. using the alpha channel of the PNG format).

If you use mandatory watermarks, remember to protect your source images by HTTP Basic Authentication.

Please note that changing the overlay settings does not affect images already cached by our CDN. In order to recalculate all images from the respective named source, please ask us to purge the cache for you.

Example

https://demo.tiny.pictures/mainOverlay/example6.jpg?width=526
Original image
Example image

Without watermark.

Output image
Example image

With partially transparent watermark set to a maximum width and height of 20 % of the original image and gravity northeast.

Parameters

url (string)
The URL of the overlay image. Leave blank to disable overlaying. The image may be cached by our servers for up to one hour.
maxWidth (float)
Fraction of the base image's width that may be covered by the overlay image.
maxHeight (float)
Fraction of the base image's height that may be covered by the overlay image.
gravity (string)
Corner of the base image the overlay image is placed in. Given as a cardinal point (center, north, northeast, east, southeast, south, southwest, west, northwest).
cutout (boolean)
Set to false to overlay the base image with the overlay image. Set to true to cut out areas of the base image based on the overlay image's alpha channel (masking).

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://demo.tiny.pictures/main/example6.jpg?width=526
Original image
Example image

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

Output image
Example 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 contain. If both width and height are set (see above), there are several types of resize operations. Possible values are contain, cover, fit, and background. They are defined according to the object-fit CSS property.
contain returns an image of the maximum dimensions that may be contained by a rectangle of the given dimensions. It preserves aspect ratio of both the image's content and the image file.
Example image resized with resizeType contain
cover 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).
Example image resized with resizeType cover
fill returns an image of the given dimensions. It ignores aspect ratio. The output image may appear stretched or shrunk in one dimension.
Example image resized with resizeType fill
background returns an image of the exact dimensions with the source image centered and contained by a rectangle of the given dimensions. Blank space is filled with either a background color or a blurred version of the source image depending on the background parameter (see below). It preserves aspect ratio.
Example image resized with background fill in red
gravity (string)
Optional. Default is center. Can only be used with resizeType cover. 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 northwest. The following example uses gravity southeast for the lower right corner.
Example image resized and cropped with gravity southeast
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.
Example image resized and cropped with custom gravity
Example image resized and cropped with custom gravity
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.
Example image resized and cropped with Shannon entropy gravity
attention sets the image's focus to the region with the highest luminance frequency, color saturation and presence of skin tones (face recognition).
Example image resized and cropped with attention gravity
background (string)
Optional. Default is 255,255,255,1.0. Can only be used with resizeType background. Sets the background for the otherwise blank space. May be specified as an rgba color or the special value blur.
Colors are coded as four comma-separated numbers. The first three numbers are the values for red, green, and blue in the integer range from 0 to 255. The fourth number is the opacity as a float ranging from 0.0 to 1.0. Please note that the jpeg format does not support opacity.
Example image resized and cropped with background fill in red
Example image resized and cropped with opaque background fill in green
blur stretches the source image to the full extent of the given dimensions, blurs it and overlays it with a resized version of itself like resizeType contain would, preserving aspect ratio. Use this feature for converting portrait to landscape images and vice versa.
Example image resized and cropped with blurred background fill

Format

Sets the output image format.

Example

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

PNG format.

Output image
Example 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 are kept as is. GIF is converted to PNG. All other formats are converted to JPEG.
Example image transformed with auto-format

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://demo.tiny.pictures/main/example1.jpg?grayscale=true&format=png&optimize=true&width=526
Original image
Example image

Without optimization.

Output image
Example 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://demo.tiny.pictures/main/example2.jpg?quality=50&width=526
Original image
Example image

100 % quality.

Output image
Example 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://demo.tiny.pictures/main/example3.jpg?trim=20&width=526
Original image
Example image

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

Output image
Example 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://demo.tiny.pictures/main/example4.jpg?blur=10&width=526
Original image
Example image
Output image
Example 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://demo.tiny.pictures/main/example5.jpg?grayscale=true&width=526
Original image
Example image
Output image
Example 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://demo.tiny.pictures/main/example1.jpg?rotate=90&width=526
Original image
Example image
Output image
Example 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://demo.tiny.pictures/main/example2.jpg?flip=true&width=526
Original image
Example image
Output image
Example 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://demo.tiny.pictures/main/example3.jpg?flop=true&width=526
Original image
Example image
Output image
Example 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://demo.tiny.pictures/main/example4.jpg?invert=true&width=526
Original image
Example image
Output image
Example image

Parameters

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

Noop

A. k. a. no operation. Skip all image operations – even the ones with default values – and relay the original source image. This parameter can only be used exclusively, e. g. if no other operation is used.

Use this parameter with caution. You'll skip all image optimization operations, which generally results in unnecessarily large file sizes.

Example

https://demo.tiny.pictures/main/example5.jpg?noop=true

Parameters

noop (boolean)
Optional. No default. When set to true or empty string, the operation is applied.

Combinations

You can combine any number of operations with each other.

Example

https://demo.tiny.pictures/main/example6.jpg?width=300&height=300&flip=true&grayscale=true&quality=50
Original image
Example image
Output image
Example image