Multi-media ad
Launch one ad from a mix of image and video creatives, each with its own optional per-card text and link.
A multi-media ad combines multiple creatives — any mix of images and videos — into one ad. Each creative can carry its own title, primary text, description, and destination link.
When to use this
Multi-media ads lets you upload up to 10 images and videos into a single ad. Meta's AI uses this pool of assets to automatically match and serve the best creative combination for each person at drive higher conversion rates
Example body
POST /meta/launches
Every key applicable to a multi-media ad, with sample values. Required: adName, adSets, 1–10 creatives[]._id, adProfiles, cta, webLink.
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Multi-Media",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "multi_media",
"creatives": [
{
"_id": "01H8YA...",
"cardTitles": ["Dresses, 40% off"],
"cardPrimaryTexts": ["Swipe into spring with our dress edit."],
"cardDescriptions": ["Free shipping over $50"],
"cardDestinations": [{ "websiteURL": "https://example.com/dresses", "displayLink": "example.com/dresses" }]
},
{
"_id": "01H8YB...",
"customThumbnail": { "_id": "01H8YT..." }
}
]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Spring is here.",
"primaryTextVariations": ["Up to 40% off spring styles", "Spring drop — shop now"],
"defaultHeadline": "Spring Sale",
"headlineVariations": ["40% off", "New season, new looks"],
"adDescription": "Free shipping on orders over $50.",
"descriptionVariations" : ["Free shipping on orders over $50.", "Flat 40% off on orders over $80."],
"webLink": "https://example.com/spring",
"displayLink": "example.com/spring",
"utm": "utm_source=facebook&utm_medium=cpc&utm_campaign=spring",
"leadGenFormId": null,
"adSchedule": { "startDate": "2026-06-01T00:00:00Z", "endDate": "2026-06-30T23:59:59Z" },
"promoCodeDetails": { "type": "manual", "manualCodes": ["SPRING40", "EARLYBIRD"] },
"aiMediaDisclosure": true
}
]
}Full schema: Create a launch.
Required fields
adName,adSetscreativeDetails.creatives— 1 to 10, each with_idadProfiles— at least one offacebook_page_id/instagram_account_idctawebLink
Missing any of these, or sending more than 10 creatives, is rejected (400). The server mints ads[].id and creativeDetails.groupId — don't send them.
Optional fields
defaultPrimaryText + primaryTextVariations,adDescription + descriptionVariations, defaultHeadline + headlineVariations, adDescription, displayLink, utm, adSchedule, promoCodeDetails, leadGenFormId, aiMediaDisclosure, per-creative cardTitles, cardPrimaryTexts, cardDescriptions, cardDestinations, and (for video creatives) customThumbnail.
Per-card overrides
Each creative can carry its own cardTitles, cardPrimaryTexts, cardDescriptions, and cardDestinations. When a per-card value is given, it overrides the matching ad-level field for that creative only; when it's omitted, the ad-level value is used for that creative instead:
| Per-card field | Overrides ad-level field |
|---|---|
cardTitles[0] | defaultHeadline |
cardPrimaryTexts[0] | defaultPrimaryText |
cardDescriptions[0] | adDescription |
cardDestinations[0].websiteURL | webLink |
cardDestinations[0].displayLink | displayLink |
Each row is independent — you can override just the title for one creative and leave its text, description, and link to inherit the ad-level defaults.
{
"_id": "01H8YA...",
"cardTitles": ["Dresses, 40% off"],
"cardPrimaryTexts": ["Swipe into spring with our dress edit."],
"cardDescriptions": ["Free shipping over $50"],
"cardDestinations": [{ "websiteURL": "https://example.com/dresses", "displayLink": "example.com/dresses" }]
}Field notes
groupType: "multi_media"— required. It is not inferred from creative count or file type, so always send it explicitly.creatives[]— any mix of image and video; media type is inferred per-creative from the uploaded file's MIME, same assingle_image/single_video.cardTitles/cardPrimaryTexts/cardDescriptions/cardDestinations— the fields multi-media ads use for per-card text and link overrides.customThumbnail— optional per video creative, same assingle_video.
Gotchas
cardTitles,cardPrimaryTexts,cardDescriptions, andcardDestinationseach accept at most one item — sending a second is rejected (400).- Multi-media ads don't use the
cardTitle/cardDescriptionsingular fields (those are forcarousel) — use the plural array forms instead.
