---
updatedAt: 2026-06-28T17:53:44.000Z
agentTools:
  projectIndex: https://developers.taboola.com/backstage-api/llms.txt
---

# creative_crop

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Field Name
      </th>

      <th style={{ textAlign: "left" }}>
        Modifier & Defaults
      </th>

      <th style={{ textAlign: "left" }}>
        Type
      </th>

      <th style={{ textAlign: "left" }}>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        creative\_crop
      </td>

      <td style={{ textAlign: "left" }}>
        Optional
      </td>

      <td style={{ textAlign: "left" }}>
        Object

        Contains `crop_data` array.
      </td>

      <td style={{ textAlign: "left" }}>
        Allows you to provide different images for specific aspect ratios.

        Use this field to upload tailored images for different placements (e.g. 16:9, 1:1).
      </td>
    </tr>
  </tbody>
</Table>

# crop\_data array

Each entry in the `crop_data` array specifies an image for a particular aspect ratio.

| Field | Type   | Description                                                                                              |
| :---- | :----- | :------------------------------------------------------------------------------------------------------- |
| ratio | Object | The aspect ratio for this image. Contains `width` and `height` integers.                                 |
| area  | Object | Optional. Cropping coordinates within the image. Contains `top_left_x`, `top_left_y`, `width`, `height`. |
| url   | String | The URL of the replacement image for this aspect ratio.                                                  |

## ratio object

| Field  | Type    | Description                                                 |
| :----- | :------ | :---------------------------------------------------------- |
| width  | Integer | The width component of the aspect ratio (e.g. 16 for 16:9). |
| height | Integer | The height component of the aspect ratio (e.g. 9 for 16:9). |

## area object

| Field        | Type    | Description                                      |
| :----------- | :------ | :----------------------------------------------- |
| top\_left\_x | Integer | X coordinate of the crop area's top-left corner. |
| top\_left\_y | Integer | Y coordinate of the crop area's top-left corner. |
| width        | Integer | Width of the crop area in pixels.                |
| height       | Integer | Height of the crop area in pixels.               |

# Example

```json
{
  "creative_crop": {
    "crop_data": [
      {
        "ratio": { "width": 16, "height": 9 },
        "url": "https://cdn.example.com/wide-image.jpg"
      },
      {
        "ratio": { "width": 1, "height": 1 },
        "url": "https://cdn.example.com/square-image.jpg"
      }
    ]
  }
}
```

> 📘 When to use creative\_crop
>
> * Use `creative_crop` when your image contains logos or text that may be cropped awkwardly at certain aspect ratios.
> * Provide a dedicated image for each aspect ratio where precise control is needed.
> * The system serves the appropriate image based on the placement's aspect ratio requirements.

> 🚧 Limitations
>
> * Multi-image cropping is not supported for motion ads. If included in a motion ad request, the `creative_crop` field is ignored.
> * Not supported by [Create a campaign item](https://developers.taboola.com/backstage-api/reference/create-a-campaign-item). Use [Create a batch of campaign items](https://developers.taboola.com/backstage-api/reference/create-a-batch-of-campaign-items), [Bulk create items](https://developers.taboola.com/backstage-api/reference/bulk-create-items-across-campaigns), or [Update a campaign item](https://developers.taboola.com/backstage-api/reference/update-a-campaign-item) instead.