Your Subdomain

Upon creating your account, your very own TwicPics subdomain 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.

Single Subdomain

Pay-As-You-Go customers get a unique, auto-generated subdomain which name cannot be changed. Pro customers can create organizations encompassing multiple subdomains which names can be changed. Enterprise customers can even go beyond subdomains and use their own domain names if they so desire.

As an introduction to TwicPics, a single subdomain is plenty enough given you are not limited to a single source of images per subdomain. We will explore the advantages of multiple subdomains later on in this documentation nonetheless.

Single Path

A subdomain is, simply put, a collection of paths that each reference a folder online.

The simplest possible configuration is to have the root of your subdomain (/) pointing to the root of your media server.

For instance, if the root of sub.twic.pics points to https://media.my-company.com/ then https://sub.twic.pics/my-image.png will point to https://media.my-company.com/my-image.png.

Passing through the subdomain has the following advantages:

  • the image is optimized right away: WEBP will be delivered to browsers that support the format, JPEG will be delivered otherwise, users with a bad connection will get a lighter image, etc
  • the image will be delivered through the TwicPics CDN, reducing latency and removing pressure on your own media server
  • the image can now be transformed using the TwicPics URL API
  • the actual location of the image is private, only TwicPics knows where it is located
  • you can further protect your images using custom headers and/or default manipulations
  • crucially, you decide and control where your images are stored and you are free to move them wherever your want, without breaking your website, provided you update your TwicPics subdomain configuration in a timely fashion

Furthermore, even if TwicPics only recognizes non-animated GIF, HEIF, JPEG, PNG and WebP files as transformable images, it will still let other files pass through, unaltered. This means you can use your TwicPics subdomain to deliver CSS or JavaScript files and take advantage of the TwicPics CDN in the process. There is obviously a limit to the size of such files but it is plenty enough for a web usage.

Multiple Paths

What if your images are spread on different, separate servers?

While it is quite common for most assets to be stored on a media server (say https://media.my-company.com/), some are still usually kept on the same server as the website (say https://www.my-company.com/).

Thankfully, the solution is as simple as creating two paths on the same subdomain!

One possible configuration would be

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

which would make it so:

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

If you were using the TwicPics Script, then:

  • a data-src referencing image:media/logo.png would point to https://media.my-company.com/logo.png
  • a data-src referencing image:web/banner.png would point to https://www.my-company.com/banner.png

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

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

would make it so:

  • https://sub.twic.pics/media/logo.png still points to https://media.my-company.com/logo.png
  • while https://sub.twic.pics/banner.png now points to https://www.my-company.com/banner.png

Keep in mind that doing so will make it impossible to access any image inside https://www.my-company.com/media/ if any existed.

Also:

  • a path can point to a subfolder of your server rather than its root
  • you can have more than two paths in your subdomain
  • two paths can point to the same server

See this configuration as a more complex example:

path folder
/ https://www.my-company.com/assets/
/logo https://media.my-company.com/images/logo/
/media https://media.my-company.com/web/

Point is you can organize your media library however you like and it will all be made available through your subdomain.

Multiple Subdomains

If you are a Pro or Enterprise customer, you can create Organizations and those Organizations can have multiple subdomains that can be named as you please.

This is pretty handy in order to switch from one environment to another, say between your production and staging environment.

Here is an example of such a two-subdomains configuration:

subdomain path folder
prod.twic.pics / https://www.my-company.com/assets/
/logo https://media.my-company.com/images/logo/
/media https://media.my-company.com/web/
staging.twic.pics / https://staging.my-company.com/assets/
/logo https://media.my-company.com/images/logo/
/media https://media.my-company.com/web/

All you have to do now is reference the subdomain corresponding to the environment you are currently in (prod.twic.pics or staging.twic.pics) throughout your source base, which is usually as simple as setting a single variable and using it whevener you reference your TwicPics subdomain.

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

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/man.jpg max=1000
https://sub.twic.pics/man.jpg?twic=v1/cover=1:1 cover=1:1/max=1000
https://sub.twic.pics/man.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/man.jpg quality=50
https://sub.twic.pics/man.jpg?twic=v1/cover=1:1 quality=50/cover=1:1
https://sub.twic.pics/man.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/man.jpg quality=50/max=1000
https://sub.twic.pics/man.jpg?twic=v1/cover=1:1 quality=50/cover=1:1/max=1000
https://sub.twic.pics/man.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.