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.

Alternatively, you can write API requests to benefit from TwicPics in environments outside the web.

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 to https://media.company.com/
Then https://subdomain.twic.pics/image.png will point to https://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:

Automated performance improvements (eg. WebP for browsers supporting it)

CDN caching to reduce latency and remove pressure from your servers

Improved compressions for devices with poor connection

Keep the real image location private from end users

Remain in control of your images are storage location

Enables using the TwicPics transformation API

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.

Introduction Limits & Error Handling

Getting Started