Paths Options

Your subdomain paths can be configured in many different ways so as to tweak, protect and control how your images are delivered.

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

All options can be accessed by opening the Advanced configuration part of the panel save for Fallback which is directly accessible.

Options are listed here in alphabetical order.

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 custom, 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:

API Call Final manipulation
https://sub.twic.pics/image.jpg max=1000
https://sub.twic.pics/image.jpg?twic=v1/cover=1:1 cover=1:1/max=1000
https://sub.twic.pics/image.jpg?twic=v1/resize=2000/quality=60 resize=2000/quality=60/max=1000

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:

API Call Final manipulation
https://sub.twic.pics/image.jpg quality=50
https://sub.twic.pics/image.jpg?twic=v1/cover=1:1 quality=50/cover=1:1
https://sub.twic.pics/image.jpg?twic=v1/resize=2000/quality=60 quality=50/resize=2000/quality=60

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?

API Call Final manipulation
https://sub.twic.pics/image.jpg quality=50/max=1000
https://sub.twic.pics/image.jpg?twic=v1/cover=1:1 quality=50/cover=1:1/max=1000
https://sub.twic.pics/image.jpg?twic=v1/resize=2000/quality=60 quality=50/resize=2000/quality=60/max=1000

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
     class="twic"
     data-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, ...) is issued by your server.

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

path folder
/ https://www.my-company.com/

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.

Note that EXIF orientation and color profiles may be changed or removed respectively still since they are used for generating the transformed image.

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 implement basic access authentication or to set up any custom header that would be checked by your server.

Doing so, you are making sure only TwicPics has access to your media library.

As a convenience, TwicPics already sends a X-TwicPics-Token header that is unique to your subdomain.

Watermark

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

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

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

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 an hour.

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

Once you're 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 center
top top
top-right top-right
right right
bottom-right bottom-right
bottom bottom
bottom-left bottom-left
left left
top-left top-left

DPR

This value works in conjunction with the dpr transformation to determine relative sizing of the watermark in relation to the image being watermarked when the watermark mode is none or fill.

The higher the watermark DPR, the smaller it will appear on the image.

DPR Example
1 1
2 2
3 3

Opacity

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

Opacity Example
1 1
0.6 0.6
0.3 0.3

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 while only none and fill modes will rely on the DPR for sizing.

Avalaible modes are:

Mode Description Example
contain watermark is fully contained in the image contain
cover watermark covers the image cover
fill watermark is fully contained in the image and repeated if needed fill
none watermark is put in the image as is none
tile watermark is repeated over the image tile

URL

URL specifies the location of the watermark image.

TwicPics will accept the usual, non-animated, formats: 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 disapear and be replaced with the watermark itself!

In case of SVG files, be aware no dynamic nor remote operation will be supported, meaning no animation and no linked content. All styles should be inlined in the file and raster images should be embedded as base64-encoded data URLs.