Fundamentals
Learn how TwicPics image & video optimization API works and interacts with JavaScript components.
How it works
Context-aware optimization
TwicPics acts as an image proxy. It requests your master image, be it on your own web server, cloud storage or DAM, then generates a device-adapted version with best-in-class compression, delivered directly to the end-user from the closest delivery point available.
Let's consider a full width banner. A Brazilian tourist roaming the streets of Paris with an iPhone will fetch a 750px wide, 33kB JPEG image from one of our two delivery points in the French capital. The same person, now using Chrome on a MacBook back in their home country, will fetch a 1440px wide, 114kB WebP image from our delivery point in São Paulo or in Rio de Janeiro, whichever is the closest.
Widths, and thus file sizes, would be different if the iPhone was in landscape mode, if Chrome did not cover the whole screen of the MacBook or if the MacBook had a retina display. TwicPics takes everything into consideration: orientation, dimension on screen, pixel density and more!
Integration
To benefit from context-aware optimizations, you only need to integrate one of our client library. The libraries understand the end user device, connection, and CSS, and send requests to the TwicPics API to perfom the necessary optimizations.
Only rarely will you need to hand-write API requests. Likely, it will only happen when you can't rely on context-aware optimization, eg. when optimizing the Largest Contentful Paint.
TwicPics services fall in two categories: a HTTP-based API and client libraries.
Client libraries include:
- Components (recommended) — JS frameworks integration with lazy loading, progressive loading, and cumulative layout shift handling out-of-the-box;
- Vanilla JS Script — if you don't use a framework.
Concepts
Domains and paths
Each workspace created in your TwicPics account comes with a unique domain which takes the <subdomain>.twic.pics
. Pro tier plans and higher can use their own domain.
A TwicPics domain is a collection of paths. Domain paths map two URLs:
- An output URL — where optimized assets will be served from
- A source URL — the storage where the media will be retrieved from
Taking the example of the subdomain.twic.pics
domain:
- If
/
points tohttps://media.company.com/
- Then
https://subdomain.twic.pics/image.png
will point tohttps://media.company.com/image.png
.
Retrieving medias from the TwicPics domain
To benefit from the TwicPics transformation & optimization features, you only need to fetch your medias from your TwicPics domain.
Medias retrieved from your TwicPics domain get the following advantages:
But that's only the tip of the iceberg. Retrieving your medias from your TwicPics domain enables you to use the full power of our API. Use it to add secure access to your images, add watermarking, or implement default transformations.