> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. ## Retrieval ### Image You can retrieve the original image. The URL is the same as in the [asset's](/references/content-delivery-api/overview) `file.url` field. [Retrieve an image](/references/images-api/images/retrieve-an-image) ## Changing formats ### Image format You can convert the image to a different format. Possible values: * `jpg` * `png` * `webp` * `gif` * `avif` * `tiff` The default is the original image format. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `fm` query parameter, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?fm=jpg ``` ### Progressive JPEGs You can request a JPEG image as a *progressive* JPEG. The progressive JPEG format stores multiple passes of an image in progressively higher detail. While a progressive image is loading, the viewer first sees a lower quality pixelated version, which gradually improves in detail, until the image is fully downloaded. This displays the image as early as possible in order to maintain the layout as designed. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with `fm=jpg&fl=progressive` as query parameters, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?fm=jpg&fl=progressive ``` ### 8-bit PNGs You can request a PNG image as a *8-bit* PNG. 8-bit PNG images support up to 256 colors and weight less than the standard 24-bit PNG equivalent. The 8-bit PNG format is mostly used for simple images, such as icons or logos. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with `fm=png&fl=png8` as query parameters, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?fm=png&fl=png8 ``` ### AVIF For images transformed into AVIF format, the image size limits as defined in [Technical Limits](https://www.contentful.com/developers/docs/technical-limits/) apply. Additionally, there is a 9 Megapixel limit on the size of the source image. The limit applies to all service tiers (see [Technical Limits](https://www.contentful.com/developers/docs/technical-limits/)). ## Resizing & cropping ### Specify width & height You can resize the image to the desired width and height. The maximum allowed value is `4000` pixels. The default is the original image width and height. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the following query parameters: * `w`: The desired width of the image in pixels (cannot be zero). * `h`: The desired height of the image in pixels (cannot be zero). ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?w=100&h=100 ``` ### Change the resizing behavior By default, images are resized to fit into the specified dimensions, only if the original asset is larger than the specified limit (width and height). The image will take up the maximum space within the bounding box that was provided, at its original aspect ratio. You can request a different behavior using the `fit` parameter. Possible values: * `pad`: Resize the image to the specified dimensions, padding the image if needed. * `fill`: Resize the image to the specified dimensions, cropping the image if needed. * `scale`: Resize the image to the specified dimensions, changing the original aspect ratio if needed. * `crop`: Crop a part of the original image to fit into the specified dimensions. * `thumb`: Create a thumbnail from the image. `pad` behavior uses [background color](#background-color) as padding color. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `fit` query parameter, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?fit=pad&w=100&h=100 ``` ### Specify focus area You can choose the focus area for resizing when using fit type `pad`, `fill`, `crop` or `thumb`. Focus area has no effect on the default or `scale` fit type. Possible values: * `center`, `top`, `right`, `left`, `bottom`. * `top_right`, `top_left`, `bottom_right`, `bottom_left`. * `face` for the largest face detected. * `faces` for all the faces detected. The default is `center`. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `f` query parameter with `fit` as `pad`, `fill`, `crop`, or `thumb`, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?f=face&fit=thumb ``` ### Crop rounded corners & circle/ellipse You can add rounded corners to your image or crop to a circle/ellipse. Possible values: * The size of the corner radius in pixels. * `max` keyword for a full circle/ellipse. The default is `0`. Rounded corners use [background color](#background-color) as padding color, unless the format is `jpg` and resizing behavior is `pad`, then default to white. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `r` query parameter, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?r=20 ``` ## Image manipulation ### Quality You can alter the quality of the image, expressed as a percentage value between `1` and `100`. Quality value is only ignored for 8-bit PNGs. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `q` query parameter, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?fm=jpg&q=50 ``` ### Background color You can choose the background color when using corner radius or the `pad` fit type. It accepts RGB values such as `rgb:9090ff`. The default is white for JEPGs and transparent for PNGs and WEBPs. Use the [Retrieve an image](/references/images-api/images/retrieve-an-image) endpoint with the `bg` query parameter, see example: ``` /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc060607df0f3baef/quwowooybuqbl6ntboz3.jpg?w=500&h=250&fit=pad&bg=rgb:ffffff ``` # Deletion To delete an image, please refer to the [CMA documentation on assets](/references/content-management-api/overview).