Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mavera.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Scenario

You’re running video ads across Facebook and Instagram but have no systematic way to evaluate why some creatives outperform others. This job pulls video ad creatives from your ad account, uploads them to Mavera Assets, and runs Video Analysis on each. The output gives you emotional, cognitive, and behavioral scoring — the “why” behind creative performance that CPM and CTR alone can’t explain.

​
Architecture

​
Code

import os, requests, time, tempfile

META = os.environ["META_ACCESS_TOKEN"]
ACCT = os.environ["META_AD_ACCOUNT_ID"]
MV = os.environ["MAVERA_API_KEY"]
GRAPH = "https://graph.facebook.com/v24.0"
MB = "https://app.mavera.io/api/v1"
MH = {"Authorization": f"Bearer {MV}"}

# 1. Pull video creatives
creatives = requests.get(
    f"{GRAPH}/{ACCT}/adcreatives",
    params={
        "access_token": META,
        "fields": "id,name,title,video_id,thumbnail_url,object_story_spec",
        "limit": 50,
    },
).json().get("data", [])

video_creatives = [c for c in creatives if c.get("video_id")]
print(f"Found {len(video_creatives)} video creatives")

results = []
for vc in video_creatives[:10]:
    vid = vc["video_id"]

    # 2. Get video source URL
    video_info = requests.get(
        f"{GRAPH}/{vid}",
        params={"access_token": META, "fields": "source,title,length"},
    ).json()
    source_url = video_info.get("source")
    if not source_url:
        print(f"  Skipping {vid} — no source URL (check permissions)")
        continue

    # 3. Download video to temp file
    vid_resp = requests.get(source_url, stream=True)
    vid_resp.raise_for_status()
    tmp = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False)
    for chunk in vid_resp.iter_content(8192):
        tmp.write(chunk)
    tmp.close()

    # 4. Upload to Mavera Assets
    with open(tmp.name, "rb") as f:
        asset = requests.post(
            f"{MB}/assets",
            headers=MH,
            files={"file": (f"{vid}.mp4", f, "video/mp4")},
        ).json()
    asset_id = asset["id"]
    os.unlink(tmp.name)

    # 5. Start Video Analysis
    analysis = requests.post(
        f"{MB}/video-analyses",
        headers={**MH, "Content-Type": "application/json"},
        json={"asset_id": asset_id, "name": vc.get("name", f"Meta Creative {vid}")},
    ).json()
    analysis_id = analysis["id"]

    # 6. Poll for completion
    for attempt in range(30):
        time.sleep(10)
        status = requests.get(
            f"{MB}/video-analyses/{analysis_id}", headers=MH
        ).json()
        if status.get("status") == "completed":
            break
        if status.get("status") == "failed":
            print(f"  Analysis failed for {vid}: {status.get('error', 'unknown')}")
            break
    else:
        print(f"  Timeout waiting for analysis of {vid}")
        continue

    results.append({
        "creative_id": vc["id"],
        "creative_name": vc.get("name", "Untitled"),
        "video_id": vid,
        "duration": video_info.get("length"),
        "analysis_id": analysis_id,
        "scores": status.get("scores", {}),
    })
    print(f"  ✓ {vc.get('name', vid)}: emotional={status.get('scores',{}).get('emotional','N/A')}")
    time.sleep(1)

print(f"\nAnalyzed {len(results)} video creatives")
for r in results:
    s = r["scores"]
    print(f"  {r['creative_name']}: "
          f"emotional={s.get('emotional','N/A')} "
          f"cognitive={s.get('cognitive','N/A')} "
          f"behavioral={s.get('behavioral','N/A')}")

​
Example Output

{
  "analyzed": 6,
  "creatives": [
    {
      "creative_name": "Summer Sale Hero — 30s",
      "video_id": "1234567890",
      "duration": 30,
      "scores": {
        "emotional": 8.2,
        "cognitive": 6.5,
        "behavioral": 7.8,
        "attention_curve": [9.1, 8.5, 7.2, 6.8, 8.9],
        "key_moments": [
          { "timestamp": 3.2, "type": "hook", "strength": 9.1 },
          { "timestamp": 18.5, "type": "cta", "strength": 8.9 }
        ]
      }
    },
    {
      "creative_name": "Testimonial — Real Users",
      "video_id": "0987654321",
      "duration": 45,
      "scores": {
        "emotional": 9.0,
        "cognitive": 7.1,
        "behavioral": 6.3
      }
    }
  ]
}

​
Error Handling

The source field requires the ads_read permission and the video must be owned by your ad account. Videos from Page posts need pages_read_engagement.
Source URLs are signed and expire. Download immediately after fetching the URL — don’t cache URLs for later.
Large videos (>2 min) can take 2–5 minutes. The polling loop allows up to 5 minutes. For longer videos, increase the attempt count or switch to webhooks if Mavera supports them.
Each GET to Graph API costs 1 point. With 10 creatives × 2 calls each = 20 points — well within limits. For 500+ creatives, batch with ?ids= param.

Meta Ads Integration

All Meta Ads jobs

Video Analysis

Full guide to Mavera Video Analysis