validate_and_prepare_assets

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

🔄 LONG-RUNNING TOOL: Validates multiple images from URLs for Performance Max campaigns. Emits MCP progress updates while downloading and validating 5-10 images (typically 5-15 seconds). Progress stages: download → validate → commit. ⚠️ CRITICAL: This tool accepts IMAGE URLS (from postimages.org), NOT base64 or file paths! 📋 **YOUR CRITICAL ROLE: URL Validator & Categorizer** **STEP 1: Call help_user_upload First** Before anything else: - Call help_user_upload() to show upload instructions - User will upload to postimages.org and paste Direct links - User provides links like: https://i.postimg.cc/ABC123/image.jpg **STEP 2: Categorize URLs by Examining Images** When user pastes URLs, YOU MUST: 1. **Request to view each image** (you can see images from URLs) 2. **Calculate aspect ratio** for each: width / height 3. **Categorize based on ratio**: - Landscape (1.8-2.0): ~1.91:1 like 1200×628px - Square (0.95-1.05): ~1:1 like 1200×1200px - Portrait (0.75-0.85): ~0.8:1 like 960×1200px - Logo: Small images or very wide (4:1) 4. **Verify minimum requirements**: - At least 1 landscape - At least 1 square (non-logo) - At least 1 logo 5. If missing types, ask user to upload more 2. **Tell them what images they need:** - **REQUIRED:** - At least 1 landscape image (1.91:1 ratio, like 1200×628px or 600×314px) - At least 1 square image (1:1 ratio, like 1200×1200px or 300×300px) - At least 1 square logo (1:1 ratio, min 128×128px, recommended 1200×1200px) - **OPTIONAL:** - Portrait images (4:5 ratio, like 960×1200px or 400×600px) - Landscape logos (4:1 ratio, like 1200×300px or 512×128px) 3. **Provide OS-specific help if user asks how to check/resize images:** - **Mac users:** - "Right-click image → Get Info → shows dimensions" - "Use Preview app → Tools → Adjust Size to resize" - "Recommended free tool: GIMP (gimp.org) for precise aspect ratio control" - **Windows users:** - "Right-click image → Properties → Details tab → shows dimensions" - "Use Paint → Resize → maintain aspect ratio checkbox" - "Recommended free tool: GIMP (gimp.org) or Paint.NET" - **Online tools (any OS):** - "Canva.com (free, easy templates for exact sizes)" - "Photopea.com (free Photoshop alternative)" - "ResizePixel.com (quick resize tool)" 4. **CRITICAL: Read, Examine, and Categorize Images BEFORE Calling This Tool:** **Step 4a: READ FILE CONTENTS (REQUIRED!)** - When user uploads images, ChatGPT stores them as files with paths like `/mnt/data/image.png` - **YOU MUST READ EACH FILE** to get the actual image data - **DO NOT** send file paths or FILE:file_xxx references to this tool - **DO NOT** send data URIs with FILE: references like `data:image/png;base64,FILE:file_xxx` - **YOU MUST** read the file contents using your file reading capabilities - Convert file contents to base64 string - Send actual base64 encoded data (the binary image bytes encoded as base64) **Step 4b: EXAMINE AND CATEGORIZE** - **USE EXTENDED THINKING** to analyze each image - When you read the image file, you can see its dimensions - Calculate aspect ratio: width / height - Categorize based on aspect ratio: * **Landscape** (1.80-2.00 ratio): ~1.91:1 images like 1200×628px * **Square** (0.95-1.05 ratio): ~1:1 images like 1200×1200px * **Portrait** (0.75-0.85 ratio): ~0.8:1 (4:5) images like 960×1200px * **Logo Square** (0.95-1.05 ratio + small size <500px): Small square logos * **Logo Landscape** (3.80-4.20 ratio): ~4:1 images like 1200×300px **Step 4c: VERIFY MINIMUM REQUIREMENTS** - Count images in each category - **REQUIRED MINIMUM**: * At least 1 landscape image * At least 1 square image (non-logo) * At least 1 logo (square or landscape) - If missing ANY required type: * Tell user: "You need at least 1 landscape, 1 square, and 1 logo image" * Ask user to upload missing types * DO NOT call this tool yet **STEP 2: Call This Tool with ACTUAL Base64 Data** ⚠️ **CRITICAL - Data Format**: ```python # ❌ WRONG - DO NOT SEND: "data:image/png;base64,FILE:file_xxx" # File reference - will fail! "/mnt/data/image.png" # File path - will fail! # ✅ CORRECT - SEND THIS: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." # Actual base64 encoded image bytes # OR just the base64 string without prefix: "iVBORw0KGgoAAAANSUhEUgAA..." # Also works ``` **How to get actual base64**: 1. Read the uploaded file from its path 2. Get the file contents (binary data) 3. Encode to base64 string 4. Pass to this tool **Example**: - User uploads `image.png` - ChatGPT stores as `/mnt/data/image123.png` - You read the file → get binary PNG data - You encode to base64 → get "iVBORw0K..." - You send to tool: `marketing_images_landscape: ["iVBORw0K..."]` **IMPORTANT**: - The tool needs ACTUAL image data to validate dimensions and aspect ratios - File references cannot be validated - You must convert files to base64 before calling this tool **Image Requirements (Google Ads PMax specs):** | Type | Aspect Ratio | Min Size | Recommended | Max File Size | |------|--------------|----------|-------------|---------------| | Landscape | 1.91:1 | 600×314px | 1200×628px | 5MB | | Square | 1:1 | 300×300px | 1200×1200px | 5MB | | Portrait | 4:5 (0.8:1) | 400×600px | 960×1200px | 5MB | | Logo Square | 1:1 | 128×128px | 1200×1200px | 5MB | | Logo Landscape | 4:1 | 512×128px | 1200×300px | 5MB | - **Tolerance:** ±2% aspect ratio deviation allowed - **Formats:** JPEG, PNG, WEBP only **STEP 3: Pre-Flight Checks (BEFORE Calling Tool)** **Check #1: Count Images** - Count how many images you categorized in each type - **REQUIRED MINIMUM**: * 1+ landscape images * 1+ square images (non-logo) * 1+ logo images - If missing ANY required type: * "I see you uploaded [N] images, but I need at least 1 landscape, 1 square, and 1 logo." * "Please upload [missing type] image(s)." * DO NOT call this tool yet * Wait for user to upload more images **Check #2: Verify Categorization** - Use extended thinking to double-check your categorization - Example thinking: * "Image 1: 1200×628 = 1.91 ratio → landscape ✓" * "Image 2: 1200×1200 = 1.0 ratio, large size → square marketing image ✓" * "Image 3: 200×200 = 1.0 ratio, small size → logo ✓" - If uncertain about categorization, explain to user and ask for clarification **STEP 4: Handle Validation Results** **If validation FAILS:** - Show the user the EXACT error message from this tool - Explain what the error means in simple terms - Provide step-by-step instructions to fix: - How to check current dimensions - What the correct dimensions should be - How to resize the image - How to re-upload **If validation SUCCEEDS:** - Celebrate! ✅ - Show the asset_bundle_id to the user - Tell them the bundle is valid for 1 hour - Move to collecting campaign text details (name, headlines, etc.) - DO NOT call create_pmax_campaign until you have ALL text details **Returns:** - SUCCESS: asset_bundle_id (UUID) + summary of validated images - FAILURE: Specific error for the first invalid image + instructions to fix **Common Validation Errors & How to Help:** 1. **Wrong aspect ratio** - Error: "Expected 1.91:1, got 2.0:1" - Help: "Your image is slightly too wide. Crop it to 1200×628px exactly." 2. **Image too small** - Error: "Minimum size is 600×314px, got 500×250px" - Help: "Use a higher resolution image or upscale this one." 3. **File too large** - Error: "File too large. Maximum 5 MB, got 6.2 MB" - Help: "Compress the image using an online tool or save as JPEG with lower quality." 4. **Wrong format** - Error: "Unsupported format 'BMP'" - Help: "Convert to JPEG or PNG format." **Example User Flow:** User: "I want to create a PMax campaign" You: "Great! Let's start by uploading your images. You'll need: - At least 1 landscape image (1200×628px recommended) - At least 1 square image (1200×1200px recommended) - At least 1 square logo (1200×1200px recommended) Click the paperclip icon (📎) to attach your images." [User uploads images] You: "Perfect! I can see your images. Let me validate them..." [Call validate_and_prepare_assets] **Execution Time:** 1-3 seconds (fast validation) **Authentication:** NOT required for this tool (validation only) **REMEMBER:** - Be extremely patient and helpful with image validation - Provide clear, actionable instructions for fixing errors - Never proceed to create_pmax_campaign without a valid asset_bundle_id - The bundle expires in 1 hour - if expired, re-validate images

{
  "arguments": {
    "marketing_images_landscape": [
      "string"
    ],
    "marketing_images_square": [
      "string"
    ],
    "logos_square": [
      "string"
    ],
    "marketing_images_portrait": [
      "string"
    ],
    "logos_landscape": [
      "string"
    ]
  }
}

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

{
  "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": "validate_and_prepare_assets"
}

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