• Cheat sheets
  • Documentation
  • API reference
  • Product updates
  • Sign in
Kontent.ai Learn
  • Try Kontent.ai
  • Plan
  • Set up
  • Model
  • Develop
  • Create
Management API v2
API Reference
    • About Management API
    • Postman collection
    • SDKs
    • Authentication
    • API keys
    • API limitations
    • Guidelines on handling changes
      • Introduction
      • Asset rendition object
        Schema
      • List renditions
        GET
      • Retrieve a rendition
        GET
      • Add a rendition
        POST
      • Modify a rendition
        PUT

Asset renditions

Whenever you customize an image (by cropping it, for example), the customized version of the original image is saved as the image’s rendition.Rendition defines what image transformation parameters need to be applied to the original image to get the customized image.
This feature isn’t available for some legacy plan subscriptions. Contact us to find out your options.

Asset rendition object

rendition_id
string · read-only · uuid
The rendition's ID.
asset_id
string · read-only · uuid
The id of the asset this rendition belongs to.
external_id
string · nullable
The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.
transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Show child attributes
last_modified
string · read-only · date-time
ISO-8601 formatted date/time of the last change to the rendition. 
JSON
{
  "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  "external_id": "rendition-external-id-01",
  "transformation": {
    "mode": "rect",
    "fit": "clip",
    "custom_width": 250,
    "custom_height": 50,
    "x": 0,
    "y": 30,
    "width": 500,
    "height": 100
  },
  "last_modified": "2022-03-01T10:54:52.1001012Z"
}

List renditions

Returns a paginated list of all renditions of the specified asset.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}/renditions

Request

Path parameters

environment_id
required · string
Identifies your environment.
asset_identifier
required · string
Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Header parameters

x-continuation
string
Determines the page of results to retrieve.To get the next page of results, check the pagination object in the API response and set the x-continuation header parameter to the value of the continuation_token property.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

// Gets the first page of results
const response = await client
  .listAssetRenditions()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .toPromise();

Response

Status (200)
A dynamically paginated list of asset renditions.
asset_renditions[]
required · array
List of renditions.
Show child attributes
pagination
required · object
Information about the next page of results.
Show child attributes

Example responses

200
400
{
  "asset_renditions": {
    "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
    "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
    "external_id": "rendition-external-id-01",
    "transformation": {
      "mode": "rect",
      "fit": "clip",
      "custom_width": 250,
      "custom_height": 50,
      "x": 0,
      "y": 30,
      "width": 500,
      "height": 100
    },
    "last_modified": "2022-03-01T10:54:52.1001012Z"
  },
  "pagination": {
    "continuation_token": "W3sidG9rZW4iOiIrUklEOn...",
    "next_page": "https://manage.kontent.ai/v2/your/chosen/list/endpoint"
  }
}

Retrieve a rendition

Retrieve a rendition of the specified asset.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
asset_identifier
required · string
Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).
rendition_identifier
required · string
Identifies a rendition by its internal ID (e.g., ce559491-0fc1-494b-96f3-244bc095de57) or external ID (e.g., external-id/hero-image-rendition).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .viewAssetRendition()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .byRenditionId('ce559491-0fc1-494b-96f3-244bc095de57')
  // .byRenditionExternalId('hero-image-rendition')
  .toPromise();

Response

Status (200)
A single asset rendition object.
rendition_id
string · read-only · uuid
The rendition's ID.
asset_id
string · read-only · uuid
The id of the asset this rendition belongs to.
external_id
string · nullable
The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.
transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Show child attributes
last_modified
string · read-only · date-time
ISO-8601 formatted date/time of the last change to the rendition. 

Example responses

200
404
{
  "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  "external_id": "rendition-external-id-01",
  "transformation": {
    "mode": "rect",
    "fit": "clip",
    "custom_width": 250,
    "custom_height": 50,
    "x": 0,
    "y": 30,
    "width": 500,
    "height": 100
  },
  "last_modified": "2022-03-01T10:54:52.1001012Z"
}

Add a rendition

Creates a new rendition of the specified asset.
POST
https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}/renditions

Request

Path parameters

environment_id
required · string
Identifies your environment.
asset_identifier
required · string
Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).

Body schema

Application/json

Specify how to transform the original asset.

external_id
string · nullable
The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.
transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Show child attributes

Request samples

Payload
TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .addAssetRendition()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .withData({
    external_id: 'hero-image-rendition',
    transformation: {
      fit: 'clip',
      mode: 'rect',
      height: 120,
      width: 240,
      x: 300,
      y: 200,
      custom_height: 360,
      custom_width: 720,
    },
  })
  .toPromise();

Response

Status (201)
The newly created rendition.
rendition_id
string · read-only · uuid
The rendition's ID.
asset_id
string · read-only · uuid
The id of the asset this rendition belongs to.
external_id
string · nullable
The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.
transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Show child attributes
last_modified
string · read-only · date-time
ISO-8601 formatted date/time of the last change to the rendition. 

Example responses

201
400
{
  "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  "external_id": "rendition-external-id-01",
  "transformation": {
    "mode": "rect",
    "fit": "clip",
    "custom_width": 250,
    "custom_height": 50,
    "x": 0,
    "y": 30,
    "width": 500,
    "height": 100
  },
  "last_modified": "2022-03-01T10:54:52.1001012Z"
}

Modify a rendition

Modify a rendition of the asset.
PUT
https://manage.kontent.ai/v2/projects/{environment_id}/assets/{asset_identifier}/renditions/{rendition_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
asset_identifier
required · string
Identifies the asset by internal ID (e.g., fcbb12e6-66a3-4672-85d9-d502d16b8d9c), codename (e.g., codename/my_asset, or external ID (e.g., external-id/my-own-asset-identifier-42).
rendition_identifier
required · string
Identifies a rendition by its internal ID (e.g., ce559491-0fc1-494b-96f3-244bc095de57) or external ID (e.g., external-id/hero-image-rendition).

Body schema

Application/json


transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Hide child attributes
mode
required · string
The transformation's mode. Only the rect mode is allowed.
fit
required · string
Controls how the output image is constrained within the provided width and height boundaries after resizing.
custom_width
required · number · int32
The output image's width in pixels. Must be smaller than width.Use custom_width if you want to resize the rectangle region selected via x, y, width, and height. That is to keep the contents of the selected rectangle region but make the output image smaller.
custom_height
required · number · int32
The output image's height in pixels. Must be smaller than height.Use custom_height if you want to resize the rectangle region selected via x, y, width, and height. That is to keep the contents of the selected rectangle region but make the output image smaller.
x
required · number · int32
Represents a position on the horizontal axis of the original image as the distance from the image's top-left corner in pixels. Combined with the y property, the coordinates specify the top-left corner of the source rectangle region defined by width and height.The x's maximum value depends on the width parameter. The whole rectangle must fit within the borders of the original image.
y
required · number · int32
Represents a position on the vertical axis of the original image as the distance from the image's top-left corner in pixels. Combined with the x property, the coordinates specify the top-left corner of the source rectangle region defined by width and height.The y's maximum value depends on the height parameter. The whole rectangle must fit within the borders of the original image.
width
required · number
Starting at the coordinates defined by x and y, specifies the width of the rectangle area.
height
required · number
Starting at the coordinates defined by x and y, specifies the height of the rectangle area.

Request samples

Payload
TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .modifyAssetRendition()
  .byAssetId('fcbb12e6-66a3-4672-85d9-d502d16b8d9c')
  // .byAssetExternalId('which-brewing-fits-you')
  .byRenditionId('ce559491-0fc1-494b-96f3-244bc095de57')
  // .byRenditionExternalId('hero-image-rendition')
  .withData({
    transformation: {
      fit: 'clip',
      mode: 'rect',
      height: 120,
      width: 240,
      x: 300,
      y: 200,
      custom_height: 360,
      custom_width: 720,
    },
  })
  .toPromise();

Response

Status (200)
The updated rendition.
rendition_id
string · read-only · uuid
The rendition's ID.
asset_id
string · read-only · uuid
The id of the asset this rendition belongs to.
external_id
string · nullable
The rendition's external ID. The external ID can be specified when adding renditions. If not specified, the external_id property is not present.
transformation
required · object
Specifies how to transform the original image asset.The image area to use for the transformation is determined by the x, y, width, and height properties. The custom_width and custom_height properties set the dimensions of the output image. The x and y coordinates define a point in the original image. The point is specified as the distance from the top-left corner of the original image asset in pixels. The whole area must be within the borders of the original image. Upscaling, that is setting the custom_width and custom_height greater than width and height, is not allowed.
Show child attributes
last_modified
string · read-only · date-time
ISO-8601 formatted date/time of the last change to the rendition. 

Example responses

200
400
{
  "rendition_id": "d866c136-8824-45f9-af39-9ebf9c31ea8f",
  "asset_id": "ba00e3ba-e217-4fc0-9f4e-90b9510d2b08",
  "external_id": "rendition-external-id-01",
  "transformation": {
    "mode": "rect",
    "fit": "clip",
    "custom_width": 250,
    "custom_height": 50,
    "x": 0,
    "y": 30,
    "width": 500,
    "height": 100
  },
  "last_modified": "2022-03-01T10:54:52.1001012Z"
}
Copyright © 2025 Kontent.ai. All rights reserved.
  • Web
  • Privacy policy
  • Cookies policy
  • Consent settings
  • Security
  • GDPR