Single video ad
Launch one video ad per adset.
A single video ad pairs one uploaded video creative with ad copy. Identical to the single image ad flow except the creative is a video.
When to use this
You have one video asset to run as-is.
Example body
POST /meta/launches
Every key applicable to a single-video ad, with sample values (required: adName, adSets, creativeDetails.creatives[]._id, adProfiles, cta, webLink):
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Sale — Hero Video",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "single_video",
"creatives": [{ "_id": "01H8YA...", "customThumbnail": { "_id": "01H8YT..." } }]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Watch the spring collection in motion.",
"primaryTextVariations": ["See the spring drop", "Spring, in motion"],
"defaultHeadline": "Spring Sale",
"headlineVariations": ["40% off", "New season"],
"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.
To run this ad in several languages, add defaultLanguage and languages — single video is one of the two formats that support it. See Multi-language ads.
Required fields
adName,adSetscreativeDetails.creatives[]._idadProfiles— at least one offacebook_page_id/instagram_account_idctawebLink
Missing any is rejected (400). The server mints ads[].id and creativeDetails.groupId.
Optional fields
defaultPrimaryText, primaryTextVariations,adDescription, descriptionVariations, defaultHeadline, headlineVariations, adDescription, displayLink, utm, adSchedule, promoCodeDetails, leadGenFormId, aiMediaDisclosure, per-creative customThumbnail.
Custom video thumbnail
To override the auto-generated video thumbnail, upload your thumbnail image like any other creative, then reference its fileId as customThumbnail._id on the video creative.
"creatives": [{ "_id": "01H8YA...", "customThumbnail": { "_id": "01H8YT..." } }]Only _id is needed — the launcher hydrates the image's file details. customThumbnail applies only to video creatives.
Field notes
- Upload first. For large videos, upload via the multipart flow and use the returned
fileIdas_idhere. groupType: single_video— optional; the launcher also infers from MIME.customThumbnail._id— optional; the uploaded thumbnail image'sfileId.
Gotchas
- Without a
customThumbnail, Meta generates the thumbnail asynchronously — the ad may show a placeholder briefly after launch. - One creative only.
- Web & App (omni-channel) ad sets accept only single image / video ads — see Ad set compatibility.
