API Reference › Meta Ads › create_meta_video_campaign

create_meta_video_campaign

Meta Ads Write

User wants to create a Meta (Facebook/Instagram) video ad campaign

Endpoint

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

Headers

Description

User wants to create a Meta (Facebook/Instagram) video 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 image ads - use `create_meta_image_campaign` instead. DO NOT USE for carousel - use `create_meta_carousel_campaign` instead. This tool creates a complete Meta video campaign with: 1. Campaign (objective, budget) 2. Ad Set (targeting, placements, schedule) 3. Video Upload (handles large files with chunked upload) 4. Ad Creative (video, text, CTA) 5. Ad (linking creative to ad set) When to use this tool: - "Create a Facebook video ad campaign" - "Launch an Instagram video ad" - "Set up a Meta Reels campaign" - "Create an ad with this video" 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") - landing_page_url: Where users go when clicking Video Source (choose ONE): - video_url: Public video URL (will be uploaded during creation) - existing_video_id: Existing Meta video ID (for reusing previously uploaded videos) Optional Parameters: - facebook_page_id: Auto-detected from connected account - instagram_account_id: Enable Instagram placements - thumbnail_url: Custom thumbnail image (Meta auto-generates if not provided) - headline: Headline below video (optional for video ads) - description: Description text (max 255 chars, recommended 30) - call_to_action: WATCH_MORE (default), LEARN_MORE, SHOP_NOW, etc. - objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS, OUTCOME_AWARENESS - locations: Country codes (default: ['US']) - age_min/age_max: Age targeting (18-65) - genders: ['male'], ['female'], or null for all - optimize_for_reels: true for vertical (9:16) videos - pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES) - pixel_event_name: Conversion event (PURCHASE, LEAD, etc.) Video Specifications: - Formats: MP4, MOV (recommended: MP4 H.264) - Max size: 4GB (recommended under 1GB) - Duration: 1 sec - 240 min (recommended 15-60 sec) - Feed: 1:1 or 4:5 aspect ratio - Stories/Reels: 9:16 aspect ratio 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.
video_urlstring optionalPublic video URL to upload. Video will be uploaded during campaign creation. Supports MP4, MOV formats. Max 4GB, recommended under 1GB. Mutually exclusive with existing_video_id.
existing_video_idstring optionalExisting Meta video ID from your Ad Library. Use this to REUSE videos already uploaded to Meta. Mutually exclusive with video_url.
thumbnail_urlstring optionalOptional custom thumbnail image URL. If not provided, Meta will auto-generate thumbnails from video.
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 requiredPrimary ad text (max 2200 characters, recommended 125 or less for optimal display). 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 video.
headlinestring optionalHeadline text (max 255 characters, recommended 40). Optional for video ads. Appears below the video on some placements.
landing_page_urlstring requiredLanding page URL where users will be directed when clicking the ad. Must be HTTPS.
call_to_actionstring optionalCall-to-action button. Options: 'WATCH_MORE' (default for video), 'LEARN_MORE', 'SHOP_NOW', 'SIGN_UP', 'DOWNLOAD', 'BOOK_TRAVEL', 'CONTACT_US'. Default: WATCH_MORE default: "WATCH_MORE"
descriptionstring optionalOptional description text (max 255 characters, recommended 30). Appears under the headline on some placements.
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, INITIATE_CHECKOUT, ADD_PAYMENT_INFO, SEARCH, VIEW_CONTENT, 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'. Default: ['US']
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 list_connected_accounts.
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.
optimize_for_reelsboolean optionalWhether to optimize for Reels placement. Set to true for vertical videos (9:16 aspect ratio). default: false
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.
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.

Example request

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

Example responses

200 — Success

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for create_meta_video_campaign)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "create_meta_video_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_video_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_video_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