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
mediais animageasset MUST match one listed pair. A larger image at the same ratio does not match. When thecardsslot declarespixel_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_sizesdoes not constrain video card media. Video cards followcard_video_max_file_size_kbandcard_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 matches1.91:1). A declaration where they disagree is invalid; neither field wins. When onlycard_image_sizesis declared, the listed sizes imply the accepted card ratios. When onlycard_aspect_ratiois declared, buyers match the ratio and choose the pixel size.
Card call to action
Each card may carry its owncta 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
ctaMUST be one of the listed values. A seller refuses any other value withCREATIVE_VALUE_NOT_ALLOWED, anderror.fieldpoints at that card’scta(for examplecreatives[0].assets.cards[2].cta). The buyer fixes it by picking a listed value. - Not declared. A card’s
ctatakes free text, and a seller does not refuse it asCREATIVE_VALUE_NOT_ALLOWED. - Optional per card.
cta_valueslimits the values a card may use. It does not makectarequired; a card that omitsctais not refused undercta_values.
sponsored_placement rather than a buyer-authored carousel bundle.
See Catalogs and Canonical formats.