create_tiktok_video_campaign

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

User wants to create a TikTok ad campaign with a VIDEO (not images). Also supports Spark Ads and Carousel with video. LONG-RUNNING TOOL: Creates a TikTok In-Feed video ad campaign. Also supports Spark Ads (boost organic posts) and Carousel ads. Additional creative types supported: - Spark Ads: Provide tiktok_item_id to boost an existing organic TikTok post as a paid ad - Carousel Ads: not supported by the TikTok API version we target — use video or Spark Ads instead - App Promotion: Set objective=APP_PROMOTION + app_id for app install campaigns Emits MCP progress updates during campaign creation (typically 30-60 seconds). Progress stages: validate - upload - commit. CRITICAL WARNING: - Call this tool ONLY ONCE per campaign - Creates REAL campaigns that cost REAL money - Do NOT retry automatically if errors occur - Report errors to user instead of retrying YOUR ROLE: TikTok Video Ads Campaign Strategist CRITICAL PRE-FLIGHT CHECKLIST - DO NOT SKIP: 1. Fix Video URL Format (CRITICAL!): Check if user provided Google Drive link: - BAD: https://drive.google.com/file/d/{FILE_ID}/view?usp=sharing - GOOD: https://drive.google.com/uc?export=download&id={FILE_ID} YOU MUST CONVERT Google Drive links! Extract FILE_ID and rebuild URL. Example: - Input: https://drive.google.com/file/d/1jTOcNDe1UfvlUka5VpD2RAblNpQ3FGm_/view?usp=sharing - Extract ID: 1jTOcNDe1UfvlUka5VpD2RAblNpQ3FGm_ - Output: https://drive.google.com/uc?export=download&id=1jTOcNDe1UfvlUka5VpD2RAblNpQ3FGm_ Other common fixes: - Dropbox: Add ?dl=1 to end of URL (not ?dl=0) - Vimeo: Use direct MP4 link, not player embed - YouTube: NOT SUPPORTED - TikTok cannot download from YouTube 2. Validate Video URL: - ALWAYS call `validate_video(video_url, platform='tiktok')` FIRST - Check response Content-Type: * GOOD: "video/mp4", "video/quicktime", "video/x-msvideo" * BAD: "text/html" (means it's a web page, not direct video) - If Content-Type is text/html, STOP and ask user for direct download link - Video requirements: * Duration: 5-60 seconds (TikTok sweet spot: 9-15 seconds) * File size: Max 500MB * Aspect ratio: 9:16 (vertical) STRONGLY preferred for TikTok * Formats: MP4, MOV, MPEG, AVI 3. Cover Image (OPTIONAL - Usually Not Needed!): DEFAULT BEHAVIOR (Recommended 95% of the time): - Do NOT provide cover_image_url parameter - TikTok automatically extracts a frame from your video as thumbnail - This is the SAFEST option - aspect ratios always match! ONLY provide cover_image_url if: - User explicitly requests a specific custom thumbnail - AND you've verified aspect ratios match (see validation below) If user insists on custom cover: - Ensure it's a direct image URL (not Google Drive share link!) - Aspect ratio MUST match video exactly: * Video 9:16 vertical - Cover 9:16 vertical (1080x1920) * Video 16:9 horizontal - Cover 16:9 horizontal (1920x1080) - If unsure: OMIT cover_image_url and explain TikTok will auto-extract 4. Research the business: - Understand products/services, target audience - Review brand messaging and offers - TikTok video best practices: hook viewers in first 3 seconds, authentic content, trending sounds/effects 5. Craft compelling ad creative: - Ad text: 12-100 chars (50 or less recommended for no truncation) - Write for TikTok's young, mobile-first audience - Use casual, conversational language - Call-to-action: WATCH_NOW, LEARN_MORE, SHOP_NOW, etc. 6. Define targeting: - Locations: Default is USA, can specify others - Age groups: TikTok core demographic is 18-34 - Gender: Unless product is gender-specific, use GENDER_UNLIMITED Required Fields: 1. campaign_name - Descriptive name (auto-suffixed with timestamp) 2. budget_daily - Minimum $50/day for video ads (higher than image ads) 3. video_url - Public video URL (must be validated first!) 4. ad_text - Main message (12-100 chars, 50 recommended) 5. landing_page_url - HTTPS URL where users land Optional Fields: - call_to_action - CTA button (default: WATCH_NOW) - cover_image_url - Custom video thumbnail (OPTIONAL - Not Recommended!) IMPORTANT: This is OPTIONAL! - Default (omit this field): TikTok auto-extracts frame from video - RECOMMENDED - Only provide if user explicitly wants custom thumbnail AND aspect ratios match If you decide to provide cover_image_url: - Aspect ratio MUST exactly match video or TikTok will reject - Video 9:16 vertical - Cover 9:16 vertical (1080x1920) - Video 16:9 horizontal - Cover 16:9 horizontal (1920x1080) - When in doubt: OMIT this field - TikTok auto-extraction always works! - target_locations - List of TikTok location IDs (default: USA) - target_age_groups - Age ranges to target - target_gender - Gender targeting (default: all) - advertiser_id - TikTok advertiser account What happens when you call this tool: 1. Creates Campaign with TRAFFIC objective 2. Creates Ad Group with PLACEMENT_TYPE_NORMAL (TikTok feed only) 3. Downloads video from URL and uploads to TikTok (UPLOAD_BY_URL with unique filename) 4. Uploads cover image (custom or auto-extracted from video) 5. Creates Ad with video + cover creative 6. Campaign goes ACTIVE immediately 7. TikTok processes video (5-15 minutes) and reviews ad creative (24 hours) Idempotency Support: - If creation fails partway, partial state is logged (campaign_id, ad_group_id, video_id) - You can retry with same parameters - system will resume from checkpoint - Prevents duplicate campaigns and video uploads Execution time: 30-60 seconds (TikTok video upload takes longer than images) Common Errors & How YOU Should Handle: 1. "text/html" Content-Type from validation: - Means URL is a web page, not direct video download - Common with: Google Drive share links, YouTube embeds - Your Action: Convert Google Drive links OR ask user for direct download URL 2. "Aspect ratio mismatch" error: - Cover image doesn't match video dimensions - Your Action: OMIT cover_image_url, tell user TikTok will auto-extract 3. "Video upload failed": - Usually means video URL became inaccessible or wrong format - Your Action: Re-validate URL, ensure it's direct download link 4. "Authorization failed": - User doesn't have TikTok connected or quota exceeded - Your Action: Guide user to connect TikTok account first Best Practices: - Start with $50-100/day budget for video (higher than images due to CPV) - Test multiple video variations (different hooks, CTAs) - Monitor video completion rate - TikTok rewards engaging videos with lower costs - First 3 seconds are critical - hook viewers immediately - Use vertical 9:16 format for best mobile experience - Add captions - 85% of TikTok is watched with sound off - Learning phase is 7 days - let algorithm optimize before making changes

{
  "arguments": {
    "campaign_name": "string",
    "ad_text": "string",
    "objective": "TRAFFIC",
    "app_id": "string",
    "app_promotion_type": "string",
    "budget_daily": 1.0,
    "budget_lifetime": 1.0,
    "schedule_end_time": "string"
  }
}

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

{
  "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_tiktok_video_campaign"
}

{
  "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_tiktok_video_campaign",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}