TwicPics API

TwicPics is powered by a URL-based API that can transform and manipulate your visual assets.

When using TwicPics Components or TwicPics Native, the API request is generated using your browser context. But in some cases, you might want to write the API requests yourself.

TwicPics API offers a broad array of transformations to manipulate your media in any way you desire.

There are two kinds of transformations: ones that actually modify the image (or video) and others that change the context of further transformations down the manipulation chain.

Syntax

All transformations follow the same structure: <name>=<parameters>

where:

<name> is the name of the transformation
<parameters> is an expression specifying the parameters for the transformation

For instance:

resize=400 will resize the image to 400 pixels in width while conserving the source image aspect ratio
resize=640x480 will resize the image to exactly 640 pixels in width per 480 pixels in height, potentially altering its aspect ratio

Fundamentals

We refer to a list of one or several transformations as a manipulation .

Transformations can be 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, TwicPics will optimize it for speed and accuracy on the fly.

Focus point

Transformations behave differently depending on which point in the image is the main focus. TwicPics 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 using the focus transformation.

Chaining transformations

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

For instance:

resize=340/resize=50p will result in an image that is 170 pixel-wide
resize=50p/focus=20x10 will put the focus point at coordinates 40x20 of the source image

Since TwicPics 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: TwicPics will simply ignore the first resize.

URL format

To perform an API call to TwicPics, you need to provide:

the image or video to manipulate
the list of transformations to be applied

The URL for an API request has the following format:

https://<your-twicpics-domain>/<path_to_image>?twic=v1/<manipulation>

Where:

https://<your-twicpics-domain>/<path_to_image> is the image path
?twic=v1/<manipulation> is a list of one or more transformations

Transformations are always applied in order. See Chaining transformations.

For instance, https://<your-twicpics-domain>/myImage.png?twic=v1/resize=450 will resize http://mydomain.com/myimage.png to a width of 450 pixels while preserving its aspect ratio.

If you wish to pass query parameters to the server delivering the source image, just add it to the query string before or after the manipulation using the usual query string separator &.

Going back to the previous example, you could use one of these two options:

https://<your-twicpics-domain>/myImage.png?twic=v1/resize=450&param=value
https://<your-twicpics-domain>/myImage.png?param=value&twic=v1/resize=450

Essentials