Basics

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

URL format

The TwicPics API is URL-based and every URL is structured as follows:

https://i.twic.pics/v1/[<manipulation>][/auth:<authentication>]/<source image>

where:

  • <manipulation> is a list of one or more transformations separated by the character /
  • <authentication> is an identifier that allows the use of any source image regardless of its domain (see the documentation about authentication for more information)
  • <source image> is the URL of the image to manipulate (both http: and https: are supported) or a placeholder expression.

Here are three basic examples:

  • https://i.twic.pics/v1/resize=450/http://mydomain.com/myimage.png will redimension http://mydomain.com/myimage.png to a width of 450 pixels while preserving its aspect ratio
  • https://i.twic.pics/v1/resize=300/anything/auth:xxx-xxx-xxx/https://mydomain.com/myimage.png will redimension https://mydomain.com/myimage.png to a width of 300 pixels while preserving its aspect ratio, on behalf of the client identified by the authentication identifier xxx-xxx-xxx
  • https://i.twic.pics/v1/resize=640x480/placeholder:auto will generate a 640 pixels wide per 480 pixels high gray colored placeholder.

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