Fetch and image, apply some transforms, and serve the transformed image.
The parameters in the URL can be configured as follows:
How output should be sent.
- Output raw image data.
- Output a JSON object which outlines the image transform found in the query string.
- Output an image which outlines the dimensions and quality options found in the query string. The colour and fit are set automatically.
- Output a JSON object with dimensions of the image (in pixels) that the
raw mode would output.
- 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 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
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
Supported source types (schemes):
- HTTP URLs of source images anywhere on the public web
- HTTPS URLs of source images anywhere on the public web
- UUID of image in Content API (both V1 and V2 are supported)
- Identifiers for current images from the the flags image set
- Identifiers for the current icons within the standard FT icon set
- Slugified names of known FT columnists and others from the standard FT headshots set
- Identifiers for button images representing common social platforms from the standard FT social images set
- Logo from the FT podcast logo set
- FT and other sub-brand logos from the standard colour FT logo set
- Editorial brands for use with bylines from the brand image set
- logos used by Specialist Titles from the specialist title set
Image transforms are applied by adding query parameters to the URL.
The available transforms are documented below:
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 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.
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
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
Type of transform to apply if the source aspect ratio does not perfectly match the target (subset of rules defined by CSS
- 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.
- 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.
- The image width and height are set to the exact dimensions given in the
height parameters, potentially stretching the image.
- 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.
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.
- The cropped image should try to focus on any detected faces.
- The cropped image should try to find an obvious point of interest and focus on that.
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.
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:
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.
Desired output format.
- auto (default)
Accept header from request to determine the best output format. For more information, see Cloudinary's documentation
- Format images as GIF
- Format images as JPEG
- Format images as PNG
- Format images as SVG (only available if source image is SVG and the requested transform does not include a resize)
Compression level for lossy encoding. May be set to
lossless. If lossless is not supported by chosen image format (JPG), the highest level will be used instead. Default is
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.
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
Requests which specify a
source parameter that does not match an FT
System Code may be rate limited.