Skip to main content
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.

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; 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 and Canonical formats.