By default, Taboola auto-crops your creative image to fit each placement's aspect ratio. This can cause problems when your image contains logos, text, or other elements that get cut off at certain sizes.

Multi-image support solves this by letting you upload separate images optimized for different aspect ratios (e.g. 16:9, 1:1, 2:1). The system serves the appropriate image based on the placement's requirements, giving you full control over how your creative appears.

Taboola also supports vertical ads, which use portrait-oriented images for mobile and other vertical placements.

👍

Vertical images

Vertical images are supported. When you provide a vertical thumbnail (height > width), the API automatically sets orientation to VERTICAL.

How it works

Every ad item requires a main image via thumbnail_url. This image is auto-cropped to fit each placement's aspect ratio.

To override auto-cropping, include the creative_crop field with a crop_data array. Each entry specifies:

• A ratio (e.g. 16:9, 1:1, 2:1)
• A url pointing to an image optimized for that ratio

When the ad is served, the system checks the placement's aspect ratio requirements and serves the matching image from your crop_data array. If no match exists, the main thumbnail_url image is cropped as usual.

📘

Ratio orientation matching

Aspect ratios must match the orientation of the main image (thumbnail_url):

• Horizontal ratios (e.g. 16:9) require a horizontal main image.
• Vertical ratios (e.g. 9:16) require a vertical main image.
• A square ratio (1:1) can be used with either orientation.

If any ratio in crop_data does not match the orientation of the main image, the API returns a 400 error.

Supported aspect ratios

Horizontal ratios

Use these ratios with horizontal thumbnails (width ≥ height):

Vertical ratios

Use these ratios with vertical thumbnails (height > width):

Fields

Aspect ratio images

Use the creative_crop field to provide tailored images for different aspect ratios. This prevents cropping issues when your image contains logos or text.

How it works

• Provide a crop_data array with entries for each aspect ratio you want to customize.
• Each entry includes a ratio (width/height) and a url pointing to the replacement image.
• The system serves the appropriate image based on the placement's aspect ratio requirements.

Examples

Create an item with aspect ratio images

The following example creates a new item with custom images for 191:100 and 16:9 aspect ratios. Required fields: url, title, thumbnail_url.

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/items

{
  "url": "https://www.example.com/article",
  "title": "Multi-image ad example",
  "thumbnail_url": "https://cdn.example.com/default-image.jpg",
  "creative_crop": {
    "crop_data": [
      {
        "ratio": { "width": 191, "height": 100 },
        "url": "https://cdn.taboola.com/libtrc/static/thumbnails/7ee2bd4ce885194a4f8d7bc7f24d8ff4.jpeg"
      },
      {
        "ratio": { "width": 16, "height": 9 },
        "url": "https://cdn.example.com/wide-image.jpg"
      }
    ]
  }
}

{
  "id": "5678",
  "campaign_id": "1234",
  "title": "Multi-image ad example",
  "thumbnail_url": "https://cdn.example.com/default-image.jpg",
  "creative_crop": {
    "crop_data": [
      {
        "ratio": { "width": 191, "height": 100 },
        "url": "https://cdn.taboola.com/libtrc/static/thumbnails/7ee2bd4ce885194a4f8d7bc7f24d8ff4.jpeg"
      },
      {
        "ratio": { "width": 16, "height": 9 },
        "url": "https://cdn.example.com/wide-image.jpg"
      }
    ]
  }
}

🚧

Motion ads limitation

Multi-image cropping is not supported for motion ads (PERFORMANCE_VIDEO). If you include creative_crop in a motion ad request, the field is ignored.

Validation rules

• Aspect ratios must match the orientation of the main image (thumbnail_url). Horizontal ratios (e.g. 16:9) require a horizontal main image. Vertical ratios (e.g. 9:16) require a vertical main image. A square ratio (1:1) can be used with either orientation. If any ratio in crop_data does not match the orientation of the main image, the API returns a 400 error.

Endpoints

Use these endpoints to create or update multi-image and vertical ads:

• Create a batch of campaign items - for 1 or more items within a single campaign.
• Bulk create items - for 1 or more items across multiple campaigns.
• Update a campaign item - to add or update aspect ratio images on an existing item.

Responses from Get a campaign item and Get all campaign items include orientation and creative_type.

Minimum dimensions

Static images must meet the following minimum dimensions:

If an image doesn't meet these requirements, the API returns 400 with an error response:

{
    "http_status": 400,
    "message": "Thumbnail resolution is invalid",
    "offending_field": "",
    "message_code": "campaign.inventory.error.server.thumbnailInvalidResolution",
    "template_parameters": []
}