Create Meta Image Campaign

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:

Campaign (objective, budget)
Ad Set (targeting, placements, schedule)
Ad Creative (image, text, CTA)
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

POST

api

tools

create_meta_image_campaign

execute

Create Meta Image Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_image_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "asset_bundle_id": "string",
    "budget_daily": 1,
    "budget_lifetime": 1,
    "campaign_name": "string",
    "end_time": "string",
    "existing_image_hash": "string",
    "headline": "string",
    "landing_page_url": "https://example.com",
    "objective": "OUTCOME_TRAFFIC",
    "primary_text": "string"
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for creating Meta single-image ad campaigns

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Create Meta Video CampaignUser 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

Create Meta Image Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_image_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "asset_bundle_id": "string",
    "budget_daily": 1,
    "budget_lifetime": 1,
    "campaign_name": "string",
    "end_time": "string",
    "existing_image_hash": "string",
    "headline": "string",
    "landing_page_url": "https://example.com",
    "objective": "OUTCOME_TRAFFIC",
    "primary_text": "string"
  }
}
'

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