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
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.
metadata
Output a JSON object with dimensions of the image (in pixels) that the raw mode would output.
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)
fticon-v1
Identifiers for the current icons within the standard FT icon set
fthead-v1
Slugified names of known FT columnists and others from the standard FT headshots set
ftsocial-v2
Identifiers for button images representing common social platforms from the standard FT social images set
ftpodcast-v1
Logo from the FT podcast logo set
ftlogo-v1
FT and other sub-brand logos from the standard colour FT logo set
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 need'll need to use some "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.
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.
gravity

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

Warning: this property is considered in a beta state. Do not rely on it in production yet, as we may make breaking changes.

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:

  1. The tint parameter used with no value (no colours given) tints the image with FT's "pink" colour.
  2. When given one colour, e.g. fff1e0, it tints the image with the given colour.
  3. 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.

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.