AI Ad Creative Analysis & Scoring

Turn ad images, videos, carousels, CSV rows, or existing Apify ads scraper datasets into structured creative intelligence. This Actor uses your OpenAI, xAI/Grok, or Anthropic Claude API key to score creatives, extract visible text, classify visual patterns, identify hooks, and return actionable improvement suggestions.

It is designed as the analysis layer after you collect ads from tools such as Facebook Ads Library scrapers, Google Ads scrapers, TikTok/Instagram ad workflows, spreadsheet exports, or your own creative library.

What you get

• Creative score, performance signal score, and combined weighted score
• Hook, likely target audience, CTA quality, and benefit clarity
• Visual tags for style, theme, tone, background, people, product, offer, and overlay text density
• OCR-style extracted text split into heading, sub-heading, and extras
• Metric-by-metric justifications for relevance, hook strength, creative quality, trust, psychology, CTA, and benefits
• Improvement suggestions written for marketers, media buyers, and creative teams
• A dataset row for every processed creative, including failure rows with an error message

Common use cases

• Rank competitor ads scraped from Facebook Ads Library or Google Ads Transparency Center
• Audit paid social creatives before launching new campaigns
• Compare image, video, and carousel creative patterns across brands
• Extract hooks and visible ad text from creative assets
• Build creative testing dashboards from Apify datasets
• Turn spreadsheet creative reviews into repeatable AI scoring

Input sources

You can use any one of these sources:

• creatives: simple JSON rows with copy, CTA, and asset URL fields
• csvInput: pasted CSV or tab-separated spreadsheet rows
• sourceDatasetId: an Apify dataset ID or name from a previous scraper run
• ads: advanced scraper-shaped JSON rows

Each creative needs at least one usable image or video URL. Multiple image URLs are treated as a carousel.

Quick start

1. Choose openai, xai, or anthropic.
2. Paste the matching API key in apiKey. Apify stores this field as a secret.
3. Add creatives with JSON, CSV, a dataset ID, or advanced ad objects.
4. Keep maxConcurrency at 1 to 3 if you are unsure about provider rate limits.
5. Run the Actor and open the default dataset overview.

Simple JSON input:

{
  "provider": "openai",
  "apiKey": "YOUR_OPENAI_API_KEY",
  "creatives": [
    {
      "id": "creative-1",
      "brand": "Example Brand",
      "body": "Turn ad creatives into measurable insights.",
      "cta": "Learn More",
      "assetUrl": "https://example.com/ad.jpg",
      "assetType": "image"
    }
  ]
}

CSV input:

id,brand,body,cta,assetUrls,assetType
creative-1,Brand,Primary ad text,Shop Now,https://example.com/ad.jpg,image
creative-2,Brand,Carousel copy,Learn More,https://example.com/slide-1.jpg;https://example.com/slide-2.jpg,carousel

Supported CSV headers include:

• id, creativeId, libraryID
• brand
• body, primaryText, text, copy
• cta, ctaText, callToAction
• assetUrl, assetUrls, asset, assets, mediaUrl, mediaUrls, imageUrl, videoUrl
• assetType, format, type
• active, runTimeDays, runningTAT, multipleVersions, similarAdCount, totalPlatforms, platforms

For multiple assets in one CSV cell, separate URLs with ;, |, or new lines.

Output

The default dataset contains one item per creative. Successful rows include:

• analysis_status
• provider, model, model_used
• libraryID, brand, source_format, media_urls
• visual_style, theme, tone, background, overlay_text
• hook, target_audience, creative_insights
• product_display, human_display, human_face_display, offer_display
• extracted_text
• metrics
• ai_score
• performance_score
• total_weighted_score
• improvement_suggestions
• analyzed_at

Failed rows are still saved with analysis_status: "failed" and an error field so downstream workflows can inspect what happened.

Provider defaults

Leave model empty to use the default model for the selected provider:

• OpenAI: gpt-5.4-mini
• xAI / Grok: grok-4.3
• Anthropic Claude: claude-sonnet-4-6

Use model if you want a different provider-supported vision model.

Video and image settings

• analyzeVideos: enables video download and frame extraction.
• maxVideoFrames: limits frames sent to the AI model.
• videoFrameIntervalSeconds: controls frame sampling frequency.
• imageInputMode: "url" passes public image URLs directly to the provider.
• imageInputMode: "download" downloads images and sends base64 data, which helps when a provider cannot fetch a public URL.
• imageDetail: use low for lower cost and high or auto when OCR/layout detail matters.

Cost notes

This Actor is bring-your-own-key for AI providers. The provider API charges go to your OpenAI, xAI, or Anthropic account. Video analysis, high image detail, more frames, and higher concurrency can increase provider cost and runtime.

If this Actor is monetized on Apify Store, the Apify price is separate from your AI provider usage and is shown before you start a run.

Limitations

• The Actor does not scrape ads by itself. Use it after you already have creative URLs or an Apify scraper dataset.
• Private, expired, or blocked media URLs may fail unless they are publicly fetchable.
• The performance score uses available metadata such as active status, runtime, variants, similar ad count, and platform count. It is not a replacement for true spend, CPA, CTR, or ROAS data.
• AI outputs can vary between providers and model versions. Use the same provider/model when comparing large batches.

Local development

npm install
npm test
npm run build

npm test runs TypeScript checks and behavior tests for input normalization and provider defaults.