Create Meta Carousel Campaign

User wants to create a Meta (Facebook/Instagram) carousel ad campaign with multiple images.

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 single image - use create_meta_image_campaign instead. DO NOT USE for video - use create_meta_video_campaign instead.

This tool creates a complete Meta carousel campaign with:

Campaign (objective, budget)
Ad Set (targeting, placements, schedule)
Multiple Image Uploads (one per card)
Ad Creative (carousel with child_attachments)
Ad (linking creative to ad set)

When to use this tool:

“Create a Facebook carousel ad”
“Launch an Instagram carousel campaign”
“Create a multi-product ad”
“Set up an ad with multiple images”

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”)
cards: Array of 2-10 cards (see card structure below)

Card Structure (each card requires):

image_url OR image_hash: Image source (one required)
landing_page_url: Where users go when clicking this card
headline: Card headline (max 45 chars)
description: Optional card description (max 20 chars)
call_to_action: Optional per-card CTA override

Optional Parameters:

facebook_page_id: Auto-detected from connected account
instagram_account_id: Enable Instagram placements
call_to_action: Default CTA for all cards (LEARN_MORE by default)
objective: OUTCOME_TRAFFIC (default), OUTCOME_SALES, OUTCOME_LEADS
locations: Country codes (default: [‘US’])
age_min/age_max: Age targeting (18-65)
genders: [‘male’], [‘female’], or null for all
multi_share_optimized: Let Meta optimize card order (default: true)
pixel_id: Meta Pixel ID for conversion tracking (required for OUTCOME_SALES)
pixel_event_name: Conversion event (PURCHASE, LEAD, etc.)

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_carousel_campaign

execute

Create Meta Carousel Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_carousel_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "budget_daily": 1,
    "budget_lifetime": 1,
    "call_to_action": "LEARN_MORE",
    "campaign_name": "string",
    "cards": [
      {
        "call_to_action": "SHOP_NOW",
        "description": "Up to 40% off",
        "headline": "Spring Sale",
        "image_url": "https://example.com/card1.jpg",
        "landing_page_url": "https://example.com/product/1"
      },
      {
        "headline": "New Arrivals",
        "image_url": "https://example.com/card2.jpg",
        "landing_page_url": "https://example.com/product/2"
      }
    ],
    "end_time": "string",
    "facebook_page_id": "string",
    "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_carousel_campaign)"
  },
  "success": true,
  "tool": "create_meta_carousel_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 carousel 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 DCO AdUser wants Meta to automatically TEST MULTIPLE IMAGES and find the best combination. This is Dynamic Creative Optimization (DCO). Meta tests all combinations of images × headlines × primary texts and optimizes delivery automatically. USE THIS TOOL when the user says ANY of these: - "test these images" / "test multiple images" - "let Meta find the winner" / "let Meta optimize" - "Dynamic Creative" / "DCO" - "which image performs best" - Provides multiple images and wants Meta to choose the best - "test combinations" / "mix and match" - "10 images × 5 headlines" DO NOT USE add_meta_ad multiple times for this — that creates separate ads (A/B test). DCO is ONE ad with multiple assets that Meta mixes and optimizes. Prerequisites: 1. You need an ad_set_id with is_dynamic_creative=true 2. If the user doesn't have one, first call `add_meta_ad_set` with `is_dynamic_creative=true` 3. Then call this tool with the image_urls and text variations Asset limits (from Meta): - Images: 2-10 (required) - Headlines: up to 5 (optional) - Primary texts: up to 5 (optional) - Descriptions: up to 5 (optional) - Total assets: max 30 DCO ad sets support only 1 ad — do NOT add more ads to a DCO ad set. Example: 5 images × 3 headlines × 2 primary texts = 30 combinations, Meta finds the winner.

Create Meta Carousel Campaign

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_carousel_campaign/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "budget_daily": 1,
    "budget_lifetime": 1,
    "call_to_action": "LEARN_MORE",
    "campaign_name": "string",
    "cards": [
      {
        "call_to_action": "SHOP_NOW",
        "description": "Up to 40% off",
        "headline": "Spring Sale",
        "image_url": "https://example.com/card1.jpg",
        "landing_page_url": "https://example.com/product/1"
      },
      {
        "headline": "New Arrivals",
        "image_url": "https://example.com/card2.jpg",
        "landing_page_url": "https://example.com/product/2"
      }
    ],
    "end_time": "string",
    "facebook_page_id": "string",
    "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_carousel_campaign)"
  },
  "success": true,
  "tool": "create_meta_carousel_campaign"
}