Create Meta DCO Ad

User 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:

You need an ad_set_id with is_dynamic_creative=true
If the user doesn’t have one, first call add_meta_ad_set with is_dynamic_creative=true
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.

POST

api

tools

create_meta_dco_ad

execute

Create Meta DCO Ad

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_dco_ad/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_set_id": "string",
    "call_to_action": "LEARN_MORE",
    "description": "string",
    "descriptions": [
      "string"
    ],
    "headline": "string",
    "headlines": [
      "string"
    ],
    "image_urls": [
      "string"
    ],
    "landing_page_url": "https://example.com",
    "primary_text": "string",
    "primary_texts": [
      "string"
    ]
  }
}
'

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

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 a Dynamic Creative Optimization (DCO) ad.

DCO lets Meta test combinations of multiple images, headlines, primary texts, and descriptions to find the best-performing mix automatically.

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 Image CampaignUser 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

Create Meta DCO Ad

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_meta_dco_ad/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_set_id": "string",
    "call_to_action": "LEARN_MORE",
    "description": "string",
    "descriptions": [
      "string"
    ],
    "headline": "string",
    "headlines": [
      "string"
    ],
    "image_urls": [
      "string"
    ],
    "landing_page_url": "https://example.com",
    "primary_text": "string",
    "primary_texts": [
      "string"
    ]
  }
}
'

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