Path Configuration

Learn how to configure your domain paths to tweak, control, and protect how your medias are delivered.

Upon creating your account, your very own TwicPics domain is available. All your image interactions will now be made through it and you will be able to attach as many image sources as you want using our powerful path system.

Path Options

The option panel can be accessed by clicking the 3 dots icon located at the right of the path description in the domain paths listing.

All options can be accessed by opening the source authentication and advanced configuration part of the panel.

Options are listed here in alphabetical order.

Canonical Link Header

For better SEO, it is recommended to have all variants of the same image reference a single master link.

TwicPics can generate the header with this "canonical link" for you automatically.

Two options are available:

• TwicPics URL: the canonical link points to your image through this path, ensuring eventual default manipulation and watermarking are applied. Your Source URL is protected: search engines will reference your TwicPics URL.
• Source URL: the canonical link points to your Source URL. Default manipulation and watermarking will not be applied. Your Source URL is made public: search engines will reference your Source URL.

Default Manipulation

For each path, you can set a default manipulation. This is especially handy in order to protect your assets from web crawlers and to avoid ever distributing the full-resolution master image.

Let us say that the root path (/) of <sub>.twic.pics has its default manipulation set to max=1000.

This default manipulation will be applied after any manipulation provided using the TwicPics API.

Let us see what we get with a few examples:

Please note that, in this example and no matter what, TwicPics will always deliver an image that is at most 1000 pixels wide.

You could also use the default manipulation to ensure a minimum image quality no matter the network conditions of the end-user. For instance, quality-min=50 would ensure no image with a quality lower than 50 would be delivered, even to users on 2G networks.

In truth, any transformation can be used and the possibilities are virtually endless.

Another neat trick is that you can add transformations before and/or after the ones provided through the API.

By placing the star symbol (*) in place of a transformation, you indicate where the manipulation provided through the API has to be placed.

Let us say, for instance, that you wish to provide a default quality of 50 while making it possible to override the value through the API. The correct manipulation for this would be quality=50/*.

Here is how it would behave in several examples:

Please note that while the first two resulting images will have a quality of 50, the third one will have a quality of 60 as specified through the API.

Of course, it is possible to create a default manipulation that will act before and after the one provided through the API.

For instance, we could combine a default quality with a maximum width by setting the default manipulation to quality=50/*/max=1000.

How will our previous examples behave in such an instance?

This is resounding success! No matter what the manipulation provided through the API is we do have a default, overridable quality of 50 and no image more than 1000 pixels wide will be delivered.

One final note: since the TwicPics Script does issue API calls under the hood, it will respect default manipulations too.

Let us assume we have the same default manipulation as in the previous example (quality=50/*/max=1000) and let us consider the following element

<img data-twic-src="image:man.jpg" />

Let us also assume this element is styled so that its width ends up being 2000 pixels. The manipulation applied to image:man.jpg will be resize=2000 but, since we have a default manipulation quality=50/*/max=1000, the actual final manipulation will be quality=50/resize=2000/max=1000. So the image quality will be 50 and its width 1000, as expected.

Image Fallback URL

This fallback image will be used if and when a 4xx status code (400, 404, etc) is issued by your server.

Consider the following path configuration for <sub>.twic.pics:

and say you have set the fallback of / to https://www.my-company.com/fallback.jpg.

At one point, you end up requesting https://<sub>.twic.pics/ilage.jpg instead of https://<sub>.twic.pics/image.jpg. TwicPics will try and request https://www.my-company.com/ilage.jpg, get a 404 in return, and thus, switch to https://www.my-company.com/fallback.jpg.

Eventual transformations will be applied to the fallback as if it were the intended target. So https://<sub>.twic.pics/ilage.jpg?twic=v1/resize=300 will return a 300 pixels wide version of https://www.my-company.com/fallback.jpg.

If, for whatever reason, requesting the fallback results in a 4xx status code then this status code will be propagated back to the requester.

If no fallback is provided, TwicPics will simply propagate the original 4xx status code.

Metadata

By default, TwicPics will filter out any metadata from your source image so as to gain precious bytes.

However, if your images contain information you need or want to still be present in the transformed image (like a copyright notice for instance), you can switch the Keep metadata button on.

Source Authentication

Secured sources may require additional credentials. We currently support the following authentication methods:

• "Basic" HTTP authentication
• Bearer tokens
• AWS Signature V4 (compatible with all S3-compatible services e.g. Google Cloud, Scaleway, and more)
• Azure SAS

Source Request Headers

For each path, you can set a list of headers to be sent to your server.

This is especially handy in order to set up any custom header that would be checked by your server.

Watermark

By switching the Add a watermark button on, you will be able to add watermarking to all images requested through the path.

You then have to provide the URL of the watermark image and several options are available for:

• where the watermark is positioned in the images: Anchor
• how the watermark is sized and if it is repeated: Mode
• how opaque the watermark has to be: Opacity

Tweaking and testing watermarking can be a bit cumbersome: it can take several minutes for the configuration to be propagated to the TwicPics servers and our CDN will retain any transformed image for at least thirty minutes and up to five days.

As such, we recommend you use an unused path (ie. one that is not in production) to test watermarking. We also recommend you rely on an incrementing URL parameter to ensure you do not hit the CDN cache.

Once you are satisfied with watermarking on your test path, simply apply the exact same configuration to your production path.

Anchor

The Anchor option determines where the watermark is positioned in the image.

Available values are:

Anchor	Example
center
top
top-right
right
bottom-right
bottom
bottom-left
left
top-left

Mode

Mode determines how the watermark should be resized and/or repeated relative to the image. All modes take the Anchor into account for initial positioning.

Available modes are:

Mode	Description	Example
contain	watermark is fully contained in the image
cover	watermark covers the image
fill	watermark is fully contained in the image and repeated if needed

Opacity

Determines how opaque the watermark should be. It is a number between 0 (invisible) to 1 (fully opaque).

Opacity	Example
1
0.6
0.3

URL

URL specifies the location of the watermark image.

TwicPics will accept the usual, non-animated, formats: AVIF, GIF, HEIF, JPEG, PNG, and WebP with the notable addition of SVG.

In case of a watermark with no transparency, be sure to use Opacity unless you want the original image to disappear and be replaced with the watermark itself!

Catch-All Path Segments

Using the character *, you can specify a "catch-all" path segment. What it means is that this section of your TwicPics URL can be anything as long as it does not contain a slash (/).

Using this technique, you can insert meaningful, arbitrary, slugs in your TwicPics URL and boost SEO.

For instance, the configuration below:

will enable the mappings below:

Catch-all path segments can appear anywhere in your path and as many times as necessary.

For instance, the configuration below:

will enable the mappings below:

When given the choice between a catch-all segment or a more specific one, TwicPics will always favor the most specific one, irrelevant of the order in which the paths have been created.

For instance, the configuration below:

will enable the mappings below:

Beware that a catch-all segment will take priority over a path finishing at the same level.

For instance, the configuration below:

will enable the mappings below:

Multiple Sources Paths

Multiple Sources Paths allow you to transform media from any storage through a single, unified, path.

Unlike regular paths, Multiple Sources Paths do not reference a Source URL but rather expect the URL of the source image to be provided at the API level.

As such, and to ensure external users cannot use TwicPics on your behalf, these URLs must be encrypted.

How It Works

When creating a Multiple Sources Path, you'll be provided with an Encryption Key.

Let's take the following example:

• A Multiple Sources Path named multi on your company.twic.pics domain
• An image found at https://example.com/image.png.

Using the Encryption Algorithm described below, you will have to encode https://example.com/image.png into something akin to aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n.

The image will be accessible through https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n and can be referenced in the src prop (or data-twic-src attribute if not using components) as image:multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n.

You can now apply transformations to the image as you would on a regular path:

• https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n?twic=v1/cover=500x500
• https://company.twic.pics/multi/aHR0cHM6Ly9zb21lLXNpdGUuY29tL3NvbWUtaW1hZ2UucG5n?twic=v1/output=preview

Encryption Algorithm

TwicPics expects the URLs to be encrypted as follows:

• The input URL is reversed (i.e. https://domain/path becomes htap/niamod//:sptth )
• The reversed URL is encrypted using the Advanced Encryption Standard Algorithm with a 128-bit key
• The resulting encrypted string is encoded in Base64
• Finally, all forward slashes are replaced by dashes in the resulting encoded string

The example below implements the encryption algorithm:

Paths Resolution

Using Absolute URLs

Paths can have any format and as such, they can look like absolute URLs.

For instance, the following configuration:

would make it so https://<sub>.twic.pics/https://www.my-company.com/assets/image.png points to https://www.my-company.com/assets/image.png.

Nothing impressive so far but it can come in handy when combined with the TwicPics Script.

Since the Script understands relative URLs in both data-twic-src, data-twic-poster and data-twic-background attributes, you can seamlessly handle assets located on the same server as your webpages.

Let's say https://www.my-company.com/my-page.html contains the following img element:

<img data-twic-src="assets/image.png" />

This will be rightfully understood as https://www.my-company.com/assets/image.png and the image will be optimized by TwicPics automagically.

Conflicting Paths

Paths do not have to be on the same hierarchical level. For instance, the following configuration:

would make it so:

• https://<sub>.twic.pics/media/logo.png points to https://media.my-company.com/logo.png
• https://<sub>.twic.pics/banner.png points to https://www.my-company.com/banner.png

Doing so will make it impossible to access any image inside https://www.my-company.com/media/.