API Reference

GET /v2/images/`:mode`/`:uri`

Fetch and image, apply some transforms, and serve the transformed image. The parameters in the URL can be configured as follows:

Param Description

Param	Description
`mode`	How output should be sent. raw Output raw image data. debug Output a JSON object which outlines the image transform found in the query string. placeholder Output an image which outlines the dimensions and quality options found in the query string. The colour and fit are set automatically. metadata Output a JSON object with dimensions of the image (in pixels) that the `raw` mode would output. purge Purge the original image and all images based on the original image from Cloudinary and Fastly. The image can take up to one hour to purge from Cloudinary and up to two hours to purge from Fastly.
`uri`	URI to use as the image source, which can be HTTP/HTTPS Source URIs must be URL-encoded when they're embedded in the URL of the image service, e.g. `/v2/images/raw/http%3A%2F%2Fexample%2Ecom%2Fimage%2Ejpg`. If you build image service URLs without help of `rawurlencode`/`encodeURIComponent` (or similar) URLs with query strings or special characters (e.g. spaces) will break. Source images may not exceed 20MB in size. Requests to larger images will result in `400` errors. Supported source types (schemes): http HTTP URLs of source images anywhere on the public web https HTTPS URLs of source images anywhere on the public web ftcms UUID of image in Content API (both V1 and V2 are supported) ftflag-v1 Identifiers for current images from the the flags image set fticon-v1 Identifiers for the current icons within the standard FT icon set fthead-v1 Slugified names of known FT Journalists ftsocial-v2 Identifiers for button images representing common social platforms from the standard FT social images set ftlogo-v1 FT and other sub-brand logos from the standard colour FT logo set app-badge-v1 App store download badges e.g. apple and android. ftbrand-v1 Editorial brands for use with bylines from the brand image set specialisttitle-v1 logos used by Specialist Titles from the specialist title set

mode

How output should be sent.

raw: Output raw image data.
debug: Output a JSON object which outlines the image transform found in the query string.
placeholder: Output an image which outlines the dimensions and quality options found in the query string. The colour and fit are set automatically.
metadata: Output a JSON object with dimensions of the image (in pixels) that the raw mode would output.
purge: Purge the original image and all images based on the original image from Cloudinary and Fastly. The image can take up to one hour to purge from Cloudinary and up to two hours to purge from Fastly.

uri

URI to use as the image source, which can be HTTP/HTTPS

Source URIs must be URL-encoded when they're embedded in the URL of the image service, e.g. /v2/images/raw/http%3A%2F%2Fexample%2Ecom%2Fimage%2Ejpg. If you build image service URLs without help of rawurlencode/encodeURIComponent (or similar) URLs with query strings or special characters (e.g. spaces) will break.

Source images may not exceed 20MB in size. Requests to larger images will result in 400 errors.

Supported source types (schemes):

http: HTTP URLs of source images anywhere on the public web
https: HTTPS URLs of source images anywhere on the public web
ftcms: UUID of image in Content API (both V1 and V2 are supported)
ftflag-v1: Identifiers for current images from the the flags image set
fticon-v1: Identifiers for the current icons within the standard FT icon set
fthead-v1: Slugified names of known FT Journalists
ftsocial-v2: Identifiers for button images representing common social platforms from the standard FT social images set
ftlogo-v1: FT and other sub-brand logos from the standard colour FT logo set
app-badge-v1: App store download badges e.g. apple and android.
ftbrand-v1: Editorial brands for use with bylines from the brand image set
specialisttitle-v1: logos used by Specialist Titles from the specialist title set

Query Parameters

Image transforms are applied by adding query parameters to the URL. The available transforms are documented below:

Param	Description
`width`	Width of desired output image in CSS pixels. When generating images for high-DPI displays avoid multiplying width, and use `dpr` argument instead. Defaults to a width that maintains the aspect of the image, or the width of the source image if `height` is also not set. The maximum allowed width is 65,500 pixels. In combination with `height`, the transformed image must not exceed 25 MegaPixels.
`height`	Height of desired output image in CSS pixels (subject to `dpr` scaling). Defaults to a height that maintains the aspect of the image, or the height of the source image if `width` is also not set. The maximum allowed height is 65,500 pixels.
`dpr`	Device Pixel Ratio, i.e. number of image pixels per CSS pixel. The default is `1`, which gives the standard 1:1 ratio of image pixels to CSS pixels. Set to `2` for high-DPI ("Retina") displays. Request to the image service with `width=100&dpr=2` will output image 200 pixels wide, but optimized to be displayed with CSS `width:100px` Note that browsers don't automatically adjust intrinsic size of images with higher DPI, so you'll need to use a "responsive image" solution, e.g. set explicit width or height, use `image-set()` or `srcset` attribute.
`fit`	Type of transform to apply if the source aspect ratio does not perfectly match the target (subset of rules defined by CSS `object-fit` property): cover (default) The image should be scaled to be as small as possible while ensuring both its dimensions are greater than or equal to the corresponding dimensions of the frame, and any cropping should be taken equally from both ends of the overflowing dimension. contain The image should be scaled to be as large as possible while ensuring both its dimensions are less than or equal to the corresponding dimensions of the frame. The frame should then be collapsed to match the aspect ratio of the image. fill The image width and height are set to the exact dimensions given in the `width` and `height` parameters, potentially stretching the image. scale-down Similarly to `contain`, the image dimensions are scaled down to be less than or equal to the corresponding dimensions of the frame, but the image is never enlarged. pad The image should be scaled to fill the specified width and height whilst preserving the original aspect ratio. Any empty space after transforming will be filled with the colour set in `bgcolor`.
`gravity`	The focal point of the image when it's been cropped to a different aspect ratio. This parameter only works when the `fit` parameter is set to `cover` (the default). faces The cropped image should try to focus on any detected faces. poi The cropped image should try to find an obvious point of interest and focus on that.
`bgcolor`	Fallback background colour to apply when the output image format does not support transparency (i.e., JPEG). Ignored if the image supports transparency. Specified as three- or six-character RGB hex code, e.g. `00ff00`
`tint`	Replaces colours in the image. Tinting only works when the source image is an SVG, and colours can be either hex codes or named colours. Different numbers of colours (separated by commas) behave differently: The `tint` parameter used with no value (no colours given) tints the image with FT's "pink" colour. When given one colour, e.g. `fff1e0`, it tints the image with the given colour. When given two or more colours, e.g. `fff1e0,ff0000`, it tints the image with the first colour. This behaviour is in place to reduce work when migrating between versions 1 and 2 of the image service, and should be considered deprecated.
`format`	Desired output format. auto (default) Use `Accept` header from request to determine the best output format. For more information, see Cloudinary's documentation gif Format images as GIF jpg Format images as JPEG png Format images as PNG svg Format images as SVG (only available if source image is SVG and the requested transform does not include a resize)
`quality`	Compression level for lossy encoding. May be set to `lowest`, `low`, `medium`, `high`, `highest`, or `lossless`. If lossless is not supported by chosen image format (JPG), the highest level will be used instead. Default is `medium`.
`source`	Name of the application making the request, used for audit purposes. This should be a valid FT System Code which relates to the application making the request.
`overlay`	URL of an image overlay
`overlay_X`	X position of overlay
`overlay_y`	Y position of overlay
`overlay_gravity`	Direction of the position of overlay. May be set to `south_west`,`south_east`,`north_west`,`north_east` .
`overlay_crop`	Crop of the overlay. May be set to: `scale` `crop`
`overlay_width`	Width of the overlay
`overlay_height`	Height of the overlay

The service stores cached copies of images as retrieved from origin. Cached copies of transformed images are cached by CDN.

Limitations

This service is meant for use in applications maintained by The Financial Times. Use by third-parties is not permitted, and non-FT requests may be rate-limited or blocked without notice.

If a request contains an HTTP Referer header, it must specify a known Financial Times hostname. Requests without referers are accepted but may be rate limited.

Requests which specify a source parameter that does not match an FT System Code may be rate limited.

API Reference

GET /v2/images/:mode/:uri

Query Parameters

Limitations

GET /v2/images/`:mode`/`:uri`