Paths Options
Your domain 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 Authentication and Fallback which are directly accessible.
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 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 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
, ...) 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.
Source Authentication
Secured sources may require additional credentials. We currently support the following authentication methods:
- "Basic" HTTP authentication
- Bearer tokens
- AWS S3 signature
X-TwicPics-Token
header that is unique to your domain.
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 to set up any custom header that would be checked by your server.
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 watermark 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 watermarking. 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 | ![]() |
top | ![]() |
top-right | ![]() |
right | ![]() |
bottom-right | ![]() |
bottom | ![]() |
bottom-left | ![]() |
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 | ![]() |
2 | ![]() |
3 | ![]() |
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 | ![]() |
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.
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 | ![]() |
none | watermark is put in the image as is | ![]() |
tile | watermark is repeated over the image | ![]() |
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!