API Reference › Meta Ads › create_meta_image_campaign

create_meta_image_campaign

Meta Ads Write

User wants to create a Meta (Facebook/Instagram) single-image ad campaign

Endpoint

POST https://api.adspirer.ai/api/v1/tools/create_meta_image_campaign/execute

Headers

Description

User wants to create a Meta (Facebook/Instagram) single-image ad campaign. REQUIRED: You MUST call `select_meta_campaign_type` first and complete ALL phases it describes (audience targeting research via `search_meta_targeting`/`browse_meta_targeting`, asset discovery via `discover_meta_assets`, and user approval) BEFORE calling this tool. IMPORTANT: This tool creates REAL campaigns that will spend money once activated. Campaign is created in PAUSED status for review. DO NOT USE for video ads - use `create_meta_video_campaign` instead. DO NOT USE for carousel/multi-image - use `create_meta_carousel_campaign` instead. This tool creates a complete Meta campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Ad Creative (image, text, CTA) 4. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook ad campaign" - "Launch an Instagram image ad" - "Set up a Meta traffic campaign" - "Create an ad with this image" Required Parameters: - campaign_name: Name for the campaign - budget_daily: Daily budget in USD (min $1, recommend $5-20 for testing) - primary_text: Main ad text (recommended 125 chars for optimal display, longer text shows with "See More") - headline: Headline below image (max 255 chars, recommended 40) - landing_page_url: Where users go when clicking Image Source (choose ONE): - asset_bundle_id: From `validate_and_prepare_meta_assets` (recommended for new images) - existing_image_hash: From `discover_meta_assets` (for reusing existing images) - image_url: Direct URL (uploaded during creation - use validate_and_prepare for better error handling) Optional Parameters: - facebook_page_id: Auto-detected from connected account. Only provide if multiple pages. - instagram_account_id: Auto-detected if linked. Enable Instagram placements. - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS - call_to_action: LEARN_MORE (default), SHOP_NOW, SIGN_UP, etc. - locations: Country codes (default: ['US']) or location objects from search_meta_targeting - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) - story_image_url: Different image for Stories/Reels (9:16, 1080x1920px). Uses asset_feed_spec. - right_column_image_url: Different image for Right Column (1.91:1, 1200x628px). Uses asset_feed_spec. Multi-Placement Creatives: If the user wants different images for different placements (Feed, Stories, Right Column), provide story_image_url and/or right_column_image_url. The main image will be used for Feed. This uses Meta's asset_feed_spec with asset_customization_rules instead of object_story_spec. After Creation — IMPORTANT: - This tool created 1 campaign + 1 ad set + 1 ad. - To add MORE ad sets (different targeting, audiences, or formats), use `add_meta_ad_set` with the returned campaign_id - To add MORE ads to the same ad set (A/B test copy/creative), use `add_meta_ad` with the returned ad_set_id - NEVER call this create tool again for the same campaign — that creates a SEPARATE campaign

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
campaign_namestring requiredCampaign name (will be automatically suffixed with timestamp for uniqueness)
objectivestring optionalCampaign objective. Options: 'OUTCOME_TRAFFIC' (website clicks), 'OUTCOME_SALES' (conversions), 'OUTCOME_LEADS' (lead forms), 'OUTCOME_AWARENESS' (reach), 'OUTCOME_ENGAGEMENT'. Default: OUTCOME_TRAFFIC default: "OUTCOME_TRAFFIC"
budget_dailynumber optionalDaily budget in account currency (minimum $1/day, recommended $5-20/day for testing). Mutually exclusive with budget_lifetime — provide exactly one.
budget_lifetimenumber optionalLifetime budget in account currency (total spend over campaign duration). REQUIRES end_time to be set. Mutually exclusive with budget_daily — provide exactly one.
end_timestring optionalCampaign/ad set end date in ISO format (e.g. '2026-04-30T23:59:59'). REQUIRED when using budget_lifetime. Optional with budget_daily.
asset_bundle_idstring optionalAsset bundle ID from validate_and_prepare_meta_assets tool. Use this for NEW image uploads. Mutually exclusive with existing_image_hash and image_url.
existing_image_hashstring optionalExisting Meta image hash from discover_meta_assets tool. Use this to REUSE images from Meta Ad Library. Mutually exclusive with asset_bundle_id and image_url.
image_urlstring optionalPublic image URL to upload (will be uploaded during campaign creation). Use validate_and_prepare_meta_assets for better error handling. Mutually exclusive with asset_bundle_id and existing_image_hash.
facebook_page_idstring optionalFacebook Page ID for the ad. Usually auto-detected from your connected account. Only provide if you have multiple pages and want to use a specific one.
primary_textstring optional**REQUIRED (this OR `primary_texts`).** Primary ad text (max 2200 characters, recommended 125 or less for optimal display). Ask the user for it before calling this tool. Supports emojis, line breaks (\n), and bullet points (e.g. '🔥 Limited Offer!\n\n✅ Free Shipping\n✅ 30-Day Returns'). This is the main message that appears above the image. ⚠️ If the user supplies MORE THAN ONE primary text variation, do NOT pick one and do NOT use this field — put ALL of them in the `primary_texts` array instead (Meta tests the combinations as Dynamic Creative in a single ad). Use this singular field only for a single body text. Exactly one of `primary_text` or `primary_texts` is required.
headlinestring optionalHeadline text (max 255 characters, recommended 40). Recommended — provide this OR `headlines`. Ask the user for it before calling this tool. Appears below the image as clickable text. ⚠️ If the user supplies MORE THAN ONE headline variation, do NOT pick one and do NOT use this field — put ALL of them in the `headlines` array instead.
landing_page_urlstring required**REQUIRED.** Landing page URL where users will be directed when clicking the ad. Must be HTTPS. Ask the user for it before calling this tool.
call_to_actionstring optionalCall-to-action button. Options: 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD', 'BOOK_TRAVEL', 'CONTACT_US', 'GET_QUOTE', 'SUBSCRIBE', 'WATCH_MORE'. Default: LEARN_MORE default: "LEARN_MORE"
descriptionstring optionalOptional description text (max 255 characters, recommended 30). Appears under the headline on some placements. If the user supplies more than one description variation, use the `descriptions` array field instead.
story_image_urlstring optionalOptional image URL for Stories/Reels placements (9:16 ratio, recommended 1080x1920px). If provided, the main image is used for Feed and this image for Stories/Reels. Meta's asset_feed_spec will be used instead of object_story_spec.
right_column_image_urlstring optionalOptional image URL for Right Column placement (1.91:1 ratio, recommended 1200x628px). If provided, Meta's asset_feed_spec will be used instead of object_story_spec.
instagram_account_idstring optionalInstagram account ID for Instagram placements. If not provided, ad will run on Facebook only.
pixel_idstring optionalMeta Pixel ID for conversion tracking. Required for OUTCOME_SALES campaigns. Use list_meta_pixels to find available pixels for your ad account.
pixel_event_namestring optionalConversion event to optimize for when pixel_id is provided. Options: PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATED_CHECKOUT, ADD_PAYMENT_INFO, SEARCH, CONTENT_VIEW, OTHER. Use OTHER with custom_conversion_id for custom pixel events. Default: PURCHASE
custom_conversion_idstring optionalCustom conversion ID for optimizing towards a specific custom conversion. When provided, pixel_event_name is ignored — Meta infers the event type from the custom conversion. Get available custom conversions from your Meta Events Manager.
destination_typestring optionalOverride the ad set destination type. By default, OUTCOME_LEADS uses ON_AD (Meta lead forms) and OUTCOME_TRAFFIC uses WEBSITE. Set to 'WEBSITE' for OUTCOME_LEADS campaigns that track conversions on your website via Meta Pixel instead of using Meta's built-in lead form. Options: WEBSITE, ON_AD, WEBSITE_AND_ON_AD. Only provide when overriding the default.
campaign_budget_optimizationboolean optionalEnable Advantage Campaign Budget (CBO). When true, the daily budget is set at the campaign level and Meta automatically distributes it across ad sets. When false (default), each ad set manages its own budget. default: false
daily_min_spend_targetnumber optionalCBO only: minimum daily spend for this ad set in account currency. Meta will try to spend at least this amount on this ad set each day.
daily_spend_capnumber optionalCBO only: maximum daily spend cap for this ad set in account currency. Meta will not spend more than this on this ad set each day.
locationsarray optionalLocation targeting. Accepts country codes (['US', 'CA']) OR location objects from search_meta_targeting ([{'key': '2421836', 'type': 'city', 'radius': 25, 'distance_unit': 'mile'}]). For city/region targeting, first call search_meta_targeting with search_type='location'. ALWAYS include the 'type' field (city/region/zip/place) on each object — a key with no type is treated as a country code and rejected by Meta. For ~dozens of cities each with a radius, pass one object per city. Default: ['US']
location_typesarray optionalGeo reach mode (a.k.a. location expansion / 'people interested in this location'). List of: 'home' (people who live there), 'recent' (recently there), 'travel_in' (people interested in / traveling to the location). Meta defaults to ['home','recent'] when omitted. To turn ON location expansion, include 'travel_in' (e.g. ['home','recent','travel_in']).
age_mininteger optionalMinimum age (18-65). Default: 18 default: 18
age_maxinteger optionalMaximum age (18-65). Default: 65 default: 65
gendersarray optionalGender targeting: ['male'], ['female'], or None for all genders
interestsarray optionalList of interest targeting objects from search_meta_targeting. Format: [{'id': '6003139266461', 'name': 'Fitness'}]. Use search_meta_targeting with search_type='interests' to find valid IDs.
behaviorsarray optionalList of behavior targeting objects from search_meta_targeting. Format: [{'id': '6002714895372', 'name': 'Small business owners'}]. Use search_meta_targeting with search_type='behaviors' to find valid IDs.
job_titlesarray optionalList of job title targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Chief Marketing Officer'}]. Use search_meta_targeting with search_type='job_titles' to find valid IDs.
work_employersarray optionalList of employer targeting objects for B2B campaigns. Format: [{'id': '123456', 'name': 'Google'}]. Use search_meta_targeting with search_type='work_employers' to find valid IDs.
life_eventsarray optionalList of life event targeting objects. Format: [{'id': '123456', 'name': 'Recently engaged'}]. Use search_meta_targeting with search_type='life_events' to find valid IDs.
education_schoolsarray optionalList of education school targeting objects. Format: [{'id': '123456', 'name': 'Harvard University'}]. Use search_meta_targeting with search_type='education_schools' to find valid IDs.
education_majorsarray optionalList of education major targeting objects. Format: [{'id': '123456', 'name': 'Computer Science'}]. Use search_meta_targeting with search_type='education_majors' to find valid IDs.
custom_audiencesarray optionalList of Custom Audience IDs to include in targeting. These are audiences created in Meta Ads Manager (website visitors, customer lists, etc.)
excluded_custom_audiencesarray optionalList of Custom Audience IDs to exclude from targeting.
ad_account_idstring optionalMeta Ad Account ID. Required for multi-account users. Get from get_connections_status.
special_ad_categoriesarray optionalSpecial ad categories for housing, credit, employment, or social issues. Options: 'HOUSING', 'CREDIT', 'EMPLOYMENT', 'ISSUES_ELECTIONS_POLITICS'. Leave empty for standard ads.
lead_form_idstring optionalLead form ID to attach when objective is OUTCOME_LEADS. Get available forms using list_meta_lead_forms tool. Only used with OUTCOME_LEADS objective.
multi_advertiserboolean optionalAllow ad to appear in multi-advertiser ad format (multiple ads shown together). Set to false to opt out. Default: Meta's default (enabled). Brands that want exclusive placement should set this to false.
url_tagsstring optionalURL parameters (e.g. 'utm_source=meta&utm_medium=cpc&utm_campaign=brand-launch') appended to the landing-page URL on every click. Use for UTM tracking. Leading '?' is stripped automatically.
ad_set_namestring optionalCustom name for the ad set. When omitted, defaults to '<campaign_name> - Ad Set'. Use this when you want a specific naming convention (e.g. 'Lookalike 1% - US - Nov 2026').
ad_namestring optionalCustom name for the first ad created with this campaign. When omitted, defaults to '<campaign_name> - Ad'. Use this when you want a specific naming convention for the initial ad.
display_linkstring optionalOptional display URL (also called 'caption') shown in the ad instead of the full landing page URL — e.g. 'brand.com' instead of 'brand.com/summer-sale-landing-page?utm=...'. Must be a domain that reflects the actual landing page domain or Meta rejects the creative at publish. NOT supported on video ads (Meta's video_data has no caption field).
advantage_audienceboolean optionalAdvantage+ Audience (Meta's AI-powered audience expansion). When True, Meta treats hard interests/behaviors/custom_audiences as suggestions rather than strict filters and can deliver beyond them for better performance. When False/None, targeting is strict — Meta only shows ads to users matching the specified filters. Sets targeting.targeting_automation.advantage_audience. NOT compatible with special_ad_categories (HOUSING/CREDIT/EMPLOYMENT/ISSUES_ELECTIONS_POLITICS) — Meta rejects Advantage+ Audience for special-category ads.
advantage_plus_creativeboolean optionalMaster switch for Meta's Advantage+ Creative AI enhancements. Set False to opt OUT of ALL granular enhancements at once (image touchups, auto-crop, text optimizations, enhanced CTA, background generation, etc.). Leave None or True to keep Meta's defaults.
disabled_creative_featuresarray optionalList of granular Advantage+ Creative features to opt OUT of individually. Valid field names (from Meta SDK): image_brightness_and_contrast, image_auto_crop, image_background_gen, image_enhancement, image_templates, image_touchups, image_uncrop, text_optimizations, enhance_cta, add_text_overlay, media_liquidity_animated_image, adapt_to_placement, text_generation, description_automation, site_extensions, product_extensions. Unknown names rejected. 'standard_enhancements' is NEVER accepted — Meta deprecated this bundled field in v22 and it triggers error_subcode 3858504 on campaign duplication.
primary_textsarray optionalList of primary text (body) variations (2-5). **USE THIS whenever the user gives you 2 or more primary texts** — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every body/headline combination, which is what users mean by 'multiple primary texts per creative'. Do NOT instead create separate ads or drop the extras into the singular primary_text field. Supersedes primary_text — provide EITHER primary_text (single) OR primary_texts (list), not both.
headlinesarray optionalList of headline (title) variations (2-5). **USE THIS whenever the user gives you 2 or more headlines** — it creates ONE ad where Meta's asset_feed_spec (Dynamic Creative) tests every combination. Do NOT instead create separate ads or drop the extras into the singular headline field. Supersedes headline — provide EITHER headline (single) OR headlines (list), not both.
descriptionsarray optionalList of description variations (2-5). Use this whenever the user gives you 2 or more descriptions — Meta's asset_feed_spec (Dynamic Creative) tests the combinations in ONE ad. Supersedes description — provide EITHER description (single) OR descriptions (list), not both.
publisher_platformsarray optionalPlatforms to show ads on. Options: 'facebook', 'instagram', 'audience_network', 'messenger'. Default: automatic (all). To exclude Audience Network/Apps, use ['facebook', 'instagram'].
facebook_positionsarray optionalFacebook placement positions. Options: 'feed', 'right_hand_column', 'marketplace', 'video_feeds', 'story', 'search', 'instream_video', 'facebook_reels'. Only include positions you WANT — omitted positions are excluded.
instagram_positionsarray optionalInstagram placement positions. Options: 'stream' (feed), 'story', 'reels', 'explore', 'explore_home', 'ig_search', 'profile_feed'. Only include positions you WANT — omitted positions are excluded.
app_idstring optionalFacebook App ID (numeric, registered at developers.facebook.com). Required for OUTCOME_APP_PROMOTION campaigns. NOTE: This is your FB App ID, NOT your iOS bundle ID (com.example.app) or Android package name. Find it in Meta App Dashboard → Settings → Basic.
app_store_urlstring optionalApp Store or Play Store listing URL for the promoted app. Required for OUTCOME_APP_PROMOTION campaigns. Examples: 'https://apps.apple.com/us/app/example/id123456789' (iOS), 'https://play.google.com/store/apps/details?id=com.example' (Android). Meta auto-detects platform from the URL.
app_event_typestring optionalOptional in-app event to optimize for. When omitted, Meta defaults to APP_INSTALLS (install optimization via the ad-set optimization_goal). Provide a specific event to optimize for in-app actions: PURCHASE, LEVEL_ACHIEVED, COMPLETE_REGISTRATION, START_TRIAL, SUBSCRIBE, ADD_TO_CART, ACHIEVEMENT_UNLOCKED, D2_RETENTION, D7_RETENTION, etc. Requires Meta SDK integration in the app to fire the event. Only valid for OUTCOME_APP_PROMOTION.
deep_link_url_iosstring optionalOptional iOS deep-link URL that opens a specific screen in the app for users who already have it installed (e.g. 'myapp://product/123'). When the user doesn't have the app, the App Store URL opens instead. Requires Universal Links / app_link_spec configured by the app team. Only valid for OUTCOME_APP_PROMOTION.
deep_link_url_androidstring optionalOptional Android deep-link URL (e.g. 'myapp://product/123' or 'intent://product/123#Intent;scheme=myapp;...'). When the user doesn't have the app, the Play Store URL opens instead. Only valid for OUTCOME_APP_PROMOTION.

Example request

{
  "arguments": {
    "campaign_name": "string",
    "landing_page_url": "https://example.com",
    "objective": "OUTCOME_TRAFFIC",
    "budget_daily": 1.0,
    "budget_lifetime": 1.0,
    "end_time": "string",
    "asset_bundle_id": "string",
    "existing_image_hash": "string"
  }
}

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for create_meta_image_campaign)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "create_meta_image_campaign"
}

400 — Tool-level error (bad arguments / multi-account selection)

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "create_meta_image_campaign"
}

402 — Quota exhausted

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "create_meta_image_campaign",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Meta Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai