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.

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

In case your original image's URL includes GET parameters in a query string, you have to add a query parameter that holds a qs-style or URL-encoded version of it.

For example,

https://tiny.pictures/example1.jpg?versionID=abcdef&test=1

becomes

https://demo.tiny.pictures/main/example1.jpg?query%5BversionID%5D=abcdef&query%5Btest%5D=1

or ?query=versionID%3Dabcdef%26test%3D1.

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=.

In case you need to apply advanced settings (e. g. Origin protection, Cache-Control header manipulation, etc.), you may use the settings parameter to specify the name of a named source. If you do (e. g. settings=main), the advanced settings of that named source are used.

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.

Authentication

You may also use image sources that are protected by HTTP Basic Authentication or hosted in a private Amazon Web Services (AWS) Simple Storage Service (S3) bucket. 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 credentials in plain text. Please choose a unique password you do not use anywhere else or create a dedicated user in AWS Identity and Access Management (IAM). Private AWS S3 buckets are identified by a source url in this format:

https://s3.<region>.amazonaws.com/<bucket>/

This is a sample permission policy that can be used to allow your AWS IAM tiny.pictures user access to your private bucket files (please replace <bucket> by your actual bucket name):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": ["s3:GetObject", "s3:GetObjectVersion"],
            "Resource": "arn:aws:s3:::<bucket>/*"
        }
    ]
}

Parameters

User name (string)
User name to be used in the preemptive HTTP Basic Authentication or AWS S3 access key id.
Password (string)
Password to be used in the preemptive HTTP Basic Authentication or AWS S3 secret access key.

Pre & post processing

For each named source, you can define a set of pre or post processing steps. They are applied before or after operations from the query string are applied, respectively.

For example, you can apply 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 pre and post processing settings does not affect images already cached by our CDN. In order to recalculate all images from the respective named source, please purge your cache.

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.

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.

825,212
bytes
Output image
Example image

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

31,913 96.1 %
bytes

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 (a faster alternative to the full face detection gravity below).
Example image resized and cropped with attention gravity
face sets the image's focus to contain and center on as many faces as possible. Faces are detected by a Computer Vision algorithm (Artificial Intelligence).
Example image resized and cropped with face 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.

398,153
bytes
Output image
Example image

JPG format.

44,479 88.8 %
bytes

Parameters

format (string)
Optional. Default is auto. Valid values are auto, jpeg, png, webp, and avif. You probably want to use the auto setting (or simply omit this parameter).
auto automatically determines the optimal image format. PNG, WebP, and AVIF are kept as is. GIF is converted to PNG. All other formats are converted to JPEG.
Example image transformed with auto-format
jpegBackground (string)
Optional. Default is 0,0,0 (black). Sets the background color that replaces the alpha channel if the image is converted from another format to JPEG. May be specified as an rgb color. Colors are coded as three comma-separated numbers for red, green, and blue in the integer range from 0 to 255.

Optimize

Lossless file size optimization for PNG output. This may reduce 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.

Example

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

Without optimization.

247,755
bytes
Output image
Example image

With optimization.

129,388 47.8 %
bytes

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.

103,844
bytes
Output image
Example image

50 % quality.

14,165 86.4 %
bytes

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.

573,000 14.1 %
pixels

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.

Remove background (AI)

Replace image background with transparent pixels and trim transparent edges. Since JPEG images don't support transparency, the image is converted to PNG automatically. Please consider setting the format to webp if your users' browsers support it because the WebP format has better compression than PNG and also supports transparency. If you need a JPEG image, please set format and jpegBackground parameters explicitly.

Example

https://demo.tiny.pictures/main/example2.jpg?removeBackground=true
Original image
Example image
PNG format
Example image
443,011
bytes
WebP format
Example image
51,970 88.3 %
bytes
JPEG format with background color
Example image
29,062 93.5 %
bytes

Parameters

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

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
35,751
bytes
Output image
Example image
12,972 63.7 %
bytes

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
45,878
bytes
Output image
Example image
39,042 14.9 %
bytes

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