Fundamentals
Log in to add to favouritesPage last updated 07 October 2026
Image transformations work by applying the query parameters of the transformation to the uri of an image. The uri for the image can be found in the uri attribute of an image sys object, returned in the JSON response from the Delivery API.
Transformations set against the image from the UI or Management API are appended as query string parameters to the sys.uri, so that when requested the transformations are applied in sequence using the Image API.
When the entry is requested without a linkDepth, the uri is not set however the transformations are still returned.
Requesting an entry from the Delivery API returns each of its images as an asset within the response JSON. A simplified example looks like this:
{
"asset": {
"title": "Fight Club Poster",
"description": "Fight Club main poster artwork",
"altText": "Fight Club",
"sys": {
"id": "a83c9fcc-51ef-41aa-878f-af5a33ba4b2f",
"projectId": "movieDb",
"contentTypeId": "Image",
"dataFormat": "asset",
"language": "en-GB",
"uri": "/images/1999/drama/fight-club.jpeg?w=1920&h=1080",
"properties": {
"filename": "fight-club.jpeg",
"fileSize": 6033,
"width": 300,
"height": 450
},
"version": {
"createdBy": "c.alahniuk",
"created": "1999-11-02T17:30:31.73",
"modifiedBy": "b.pitt",
"modified": "1999-11-02T17:30:31.73",
"publishedBy": "d.fincher",
"published": "1999-11-02T17:30:31.73",
"versionNo": "1.0"
}
}
},
"caption": "Fight club is a great film!",
"altText": "The 1999 Fight Club movie poster.",
"transformations": "w=1920&h=1080"
}How a request is applied
Before any parameter is applied, the image is turned the right way up using the orientation recorded by the camera that took it, so widths, heights, crop positions and focal points all refer to the upright image. The parameters are then applied one after another in the order they are given, which is covered on the multiple transformations page.
Parameter names and values
Most parameters have a short name as well as a full one, and the two are interchangeable: ?width=500&format=webp and ?w=500&f=webp request the same image. The parameter reference lists them all.
A parameter the Image API does not recognise, or a value it cannot use, is ignored rather than reported, and the rest of the request is still applied. A misspelled parameter or an out of range value therefore shows up as a transformation that appears to do nothing, so check the spelling and the value first when an image does not come back as expected.
Query string values are used exactly as they are written and are not URL decoded, so characters such as the comma in a focal point must be sent literally rather than encoded as %2C.