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.

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.

pagination

required · object

Information about the next page of results.

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

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

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

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

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

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"
}

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

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"
}

// 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();

{ "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" } }

// 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();

{ "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" }

// 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();

// 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();