> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Carousel Ads

> Canonical image-carousel creative contracts for multi-card advertising.

Use `image_carousel` when one creative contains an ordered set of cards. Card count, fields, image constraints, and optional hero assets live in canonical parameters and slots.

```json theme={null}
{
  "format_option_id": "product_carousel",
  "format_kind": "image_carousel",
  "params": {
    "min_cards": 3,
    "max_cards": 10,
    "card_aspect_ratio": "1:1",
    "card_image_sizes": [{ "width": 1080, "height": 1080 }],
    "cta_values": ["SHOP_NOW", "LEARN_MORE"],
    "slots": [
      { "asset_group_id": "cards", "asset_type": "card", "required": true, "min": 3, "max": 10 },
      { "asset_group_id": "landing_page_url", "asset_type": "url", "required": false }
    ]
  }
}
```

```json theme={null}
{
  "format_kind": "image_carousel",
  "assets": {
    "cards": [
      {
        "asset_type": "card",
        "headline": "Trail Pro",
        "cta": "SHOP_NOW",
        "media": { "asset_type": "image", "url": "https://cdn.acmeoutdoor.example/trail-pro.jpg" },
        "landing_page_url": { "asset_type": "url", "url": "https://acmeoutdoor.example/trail-pro" }
      },
      {
        "asset_type": "card",
        "headline": "Summit Pack",
        "cta": "SHOP_NOW",
        "media": { "asset_type": "image", "url": "https://cdn.acmeoutdoor.example/summit-pack.jpg" },
        "landing_page_url": { "asset_type": "url", "url": "https://acmeoutdoor.example/summit-pack" }
      },
      {
        "asset_type": "card",
        "headline": "Alpine Shell",
        "cta": "LEARN_MORE",
        "media": { "asset_type": "image", "url": "https://cdn.acmeoutdoor.example/alpine-shell.jpg" },
        "landing_page_url": { "asset_type": "url", "url": "https://acmeoutdoor.example/alpine-shell" }
      }
    ]
  }
}
```

## Card image size

`card_aspect_ratio` fixes the shape every card shares. `card_image_sizes` (added in AdCP 3.3) fixes the pixel size of card images. It is a list of accepted logical `{ width, height }` pairs, the same shape as `main_image_sizes` on `native_in_feed`.

* **Exact match.** Each card whose `media` is an `image` asset MUST match one listed pair. A larger image at the same ratio does not match. When the `cards` slot declares `pixel_ratios`, the intrinsic size is the matched pair times the selected ratio, as described under [pixel ratios](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/creative/canonical-formats.md); without it, 1x.
* **One shape per carousel.** Mixed orientations are not allowed, so every card image in one creative matches pairs of the same aspect ratio. A product that accepts 1:1 and 4:5 cards lists both, and each creative picks one.
* **Images only.** `card_image_sizes` does not constrain video card media. Video cards follow `card_video_max_file_size_kb` and `card_video_max_duration_ms`.
* **Agreement with `card_aspect_ratio`.** When both are declared, every listed pair MUST have that ratio, within 1% (so 1200×627 matches `1.91:1`). A declaration where they disagree is invalid; neither field wins. When only `card_image_sizes` is declared, the listed sizes imply the accepted card ratios. When only `card_aspect_ratio` is declared, buyers match the ratio and choose the pixel size.

## Card call to action

Each card may carry its own `cta` label, so one carousel can show `SHOP_NOW` on product cards and `LEARN_MORE` on a story card. `cta_values` (added in AdCP 3.3) governs that per-card `cta`. It has the same shape as `cta_values` on `native_in_feed` and `image`.

* **Declared.** Every card's `cta` MUST be one of the listed values. A seller refuses any other value with `CREATIVE_VALUE_NOT_ALLOWED`, and `error.field` points at that card's `cta` (for example `creatives[0].assets.cards[2].cta`). The buyer fixes it by picking a listed value.
* **Not declared.** A card's `cta` takes free text, and a seller does not refuse it as `CREATIVE_VALUE_NOT_ALLOWED`.
* **Optional per card.** `cta_values` limits the values a card may use. It does not make `cta` required; a card that omits `cta` is not refused under `cta_values`.

For catalog-composed collections where the seller reads product rows and renders tiles, use `sponsored_placement` rather than a buyer-authored carousel bundle.

See [Catalogs](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/creative/catalogs.md) and [Canonical formats](https://docs.adcontextprotocol.org/dist/docs/3.3.0-rc.0/creative/canonical-formats.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.