Basics

TwicPics is powered by a URL-based API that can be used to transform and manipulate images.

URL format

In order to perform an API call to TwicPics you need to provide:

  • the image you want to manipulate
  • the manipulation you want to apply to the image

As seen in the domain section, your source image will be accessible through

https://<sub>.twic.pics/<path_to_image>

The manipulation part can be provided in a query string of the following form:

?twic=v1/<manipulation>

where <manipulation> is a list of one or more transformations separated by the character /.

So the final URL format is as follows:

https://<sub>.twic.pics/<path_to_image>?twic=v1/<manipulation>

For instance, provided the root (/) of subdomain <sub> points to http://mydomain.com/, https://<sub>.twic.pics/myImage.png?twic=v1/resize=450 will redimension http://mydomain.com/myimage.png to a width of 450 pixels while preserving its aspect ratio.

If you wish to pass query parameters to the server delivering the source image, just add it to the query string before or after the manipulation using the usual query string separator &.

Going back to the previous example but, this time, wanting to manipulate http://mydomain.com/myimage.png?param=value you could use one of these two options:

  • https://<sub>.twic.pics/myImage.png?twic=v1/resize=450&param=value
  • https://<sub>.twic.pics/myImage.png?param=value&twic=v1/resize=450

Alternative URL format

While the format presented in the previous section is the preferred one and should always be used when making direct API calls to manipulate images, there exists an alternative.

This secondary format can be used internally by the TwicPics Script and can be useful to you if you want to manipulate placeholders.

The alternative format goes as follows:

https://<sub>.twic.pics/v1/[<manipulation>/]<source_image>

where <source_image> is one of:

For instance:

  • https://<sub>.twic.pics/v1/resize=640x480/placeholder:auto will generate a 640 pixels wide per 480 pixels high gray colored placeholder
  • and https://<sub>.twic.pics/v1/resize=450/image:myImage.png?param=value is strictly equivalent to the https://<sub>.twic.pics/myImage.png?twic=v1/resize=450&param=value expression seen in the previous section

The Script will issue API calls in both URL formats depending on the protocol of the URLs specified in data-twic-src, data-twic-poster or data-twic-background. Make sure to use a "prefixed-by-protocol" <source_image>-compatible expression inside those attributes. That is:

If you used absolute URLs as paths in your domain configuration then you can relax this constraint and use:

  • absolute http: and/or https: URLs, provided they have corresponding paths in your domain
  • relative URLs, provided they convert to absolute URLs that have corresponding paths in your domain

Error reporting

Whenever something goes wrong, TwicPics will issue an HTTP error with a sensible status code and a short explanation in plain text as a body.

TwicPics will error when:

  • there is a syntax error in the manipulation expression
  • the authentication identifier is invalid
  • the URL of the source image is not well-formed or its protocol is not supported
  • the domain of the source image is not registered (see the documentation about domain name registration)
  • the source image is unreachable (ie. the GET request to retrieve it resulted in an HTTP error)
  • the source image is of an unsupported format (only AVIF, GIF, HEIF, JPEG, PNG and WebP are currently supported)
  • the source image, the output image or any intermediate image created while processing the transformations doesn't respect the internal pixel and/or byte size limits of TwicPics (ie. one of the images has a dimension of zero or is "too big")
  • a transformation ends up cropping outside of the image (for instance when attempting to crop 500 pixels out of an image that is only 200 pixels wide)
Whenever an image does not show in your web page, be sure to check the network tab of your favorite dev tool for those red-colored lines indicative of a network error.
responsive images

The All-In-One Toolbox For Your Images

The simplest, most powerful way to tackle responsive images.