Single image ad
Launch one static-image ad per adset — the simplest creative format.
A single image ad pairs one uploaded image creative with ad copy. Use it for static promotions with no carousel or product catalog.
When to use this
You have one image to run as-is. One ad is created per entry in adSets.
Example body
POST /meta/launches
Every key applicable to a single-image ad, with sample values. Required: adName, adSets, creativeDetails.creatives[]._id, adProfiles, cta, webLink. The rest are optional.
{
"adAccountId": "01H8Y4...",
"platform": "meta",
"ads": [
{
"adName": "Spring Sale — Hero",
"adSets": ["123456789012345"],
"creativeDetails": {
"groupType": "single_image",
"creatives": [{ "_id": "01H8YA..." }]
},
"adProfiles": {
"facebook_page_id": "123456789012345",
"instagram_account_id": "987654321098765",
"page_backed_instagram_account_id": null
},
"cta": "SHOP_NOW",
"defaultPrimaryText": "Up to 40% off this spring.",
"primaryTextVariations": ["Limited-time spring sale, up to 40% off", "Spring fashion sale ends Sunday"],
"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.
To run this ad in several languages, add defaultLanguage and languages — single image 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 of these 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. Sending primaryTextVariations makes defaultPrimaryText required (same for headlines). A primary text or headline and its variations must each be unique.
Field notes
creativeDetails.creatives[]._id— thefileIdfrom Upload a file. Send only_id; the launcher hydrates the rest (versionId, mediaKey, dimensions) at launch time.groupType: single_image— optional but recommended; the launcher also infers the format from the file's MIME type.adProfiles.facebook_page_id— the identity the ad publishes under.
Gotchas
- One creative only. For 2+ creatives, use
carouselinstead. groupIdand each ad'sidare not accepted — the server mints them.- Web & App (omni-channel) ad sets accept only single image / video ads — see Ad set compatibility.
