Skip to main content

​
Overview

The Video Analysis API provides comprehensive analysis of videos and advertisements, measuring emotional, cognitive, behavioral, and technical metrics. Perfect for optimizing ad creatives, understanding viewer engagement, and improving video content.

​
Before You Start

Video analysis requires a video file that has been uploaded to Mavera. You cannot analyze a file that lives only on your local machine or a third-party URL. The flow is:
1

Upload the video

Use the Files API to upload your video. Follow the presigned URL flow: POST /files/upload-url → PUT to the upload URL → POST /files to create the record. You receive a file ID (this becomes asset_id).
2

Create the analysis

Call POST /video-analyses with asset_id, plus goal, brand, product, and analysis settings.
3

Poll for completion

Analysis runs asynchronously. Poll GET /video-analyses/{id} every 15–30 seconds until status is COMPLETED. Typical runtime: 2–10 minutes depending on video length.
4

Read results and optionally chat

Use results.full_video_metrics and results.chunks for metrics. Use POST /video-analyses/{id}/chat to ask natural-language questions about the analysis.
For a full walkthrough including upload code, see Tutorial: Video Ad Analysis.

​
Key Metrics

Emotional

Sentiment, emotional triggers, mood progression

Cognitive

Attention, comprehension, memory encoding

Behavioral

Call-to-action effectiveness, engagement drivers

Technical

Pacing, visual quality, audio analysis

​
Creating an Analysis

import requests

response = requests.post(
    "https://app.mavera.io/api/v1/video-analyses",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "title": "Q1 Product Ad Analysis",
        "asset_id": "asset_video_123",  # Your uploaded video
        "goal": "Analyze viewer engagement and emotional response",
        "brand": "Your Brand",
        "product": "Product Name",
        "primary_intent": "Drive product awareness",
        "chunk_duration": 5,  # Analyze in 5-second chunks
        "frames_per_chunk": 3,
        "workspace_id": "your_workspace_id"
    }
)

analysis = response.json()
print(f"Analysis ID: {analysis['id']}")
print(f"Status: {analysis['status']}")

​
Retrieving Results

Analysis runs asynchronously. Poll GET /video-analyses/{id} until status is COMPLETED.

​
Polling Pattern

import time

def wait_for_completion(analysis_id, max_wait_minutes=15):
    for _ in range(max_wait_minutes * 4):
        resp = requests.get(
            f"https://app.mavera.io/api/v1/video-analyses/{analysis_id}",
            headers={"Authorization": "Bearer mvra_live_your_key_here"}
        )
        data = resp.json()
        if "error" in data:
            raise Exception(data["error"]["message"])
        if data.get("status") == "COMPLETED":
            return data
        time.sleep(15)
    raise TimeoutError("Analysis did not complete in time")

​
Reading Metrics

result = wait_for_completion(analysis_id)
metrics = result["results"]["full_video_metrics"]
print(f"Overall Score: {metrics['overall_score']}/100")
print(f"Emotional Impact: {metrics['emotional_impact']}/10")
print(f"Attention Score: {metrics['attention_score']}/10")

for chunk in result["results"]["chunks"]:
    print(f"Timestamp {chunk['start_time']}-{chunk['end_time']}:")
    print(f"  Engagement: {chunk['engagement_score']}")
    print(f"  Key Moments: {chunk['key_moments']}")

​
Chat About Results

Ask natural-language questions about your completed analysis. The chat endpoint has full context of the metrics and chunks. 
response = requests.post(
    f"https://app.mavera.io/api/v1/video-analyses/{analysis_id}/chat",
    headers={"Authorization": "Bearer mvra_live_your_key_here"},
    json={
        "message": "What are the weakest moments in this video and how can I improve them?"
    }
)

data = response.json()
if "error" not in data:
    print(data.get("content", ""))
Example questions:
  • “What are the weakest moments in this video and how can I improve them?”
  • “Which segment has the best emotional impact?”
  • “Summarize the top 3 recommendations for the next version.”

​
Response Format

{
  "id": "va_abc123",
  "title": "Q1 Product Ad Analysis",
  "status": "COMPLETED",
  "results": {
    "full_video_metrics": {
      "overall_score": 78,
      "emotional_impact": 8.2,
      "attention_score": 7.5,
      "brand_recall_likelihood": 0.72,
      "cta_effectiveness": 6.8
    },
    "chunks": [
      {
        "start_time": 0,
        "end_time": 5,
        "engagement_score": 8.5,
        "emotional_valence": "positive",
        "key_moments": ["Strong opening hook"],
        "recommendations": []
      }
    ],
    "recommendations": [
      "Consider shortening the middle section",
      "Add stronger CTA at 0:45"
    ]
  },
  "usage": {
    "credits_used": 250
  }
}

​
Credit Costs

Video LengthApproximate Cost
< 30 seconds100-150 credits
30s - 1 min150-250 credits
1-3 minutes250-400 credits
3+ minutes400+ credits

​
Best Practices

Start with 15–60 second clips to iterate quickly. Longer videos use more credits and take longer to process.
The goal, brand, and primary_intent parameters improve relevance of metrics and recommendations.
Shorter chunks (e.g. 3–5 seconds) give finer granularity; longer chunks (e.g. 10 seconds) reduce processing time.
Run multiple analyses and compare overall_score, emotional_impact, and cta_effectiveness across variants.

Tutorial

Full end-to-end script: upload → analyze → chat

Quickstart

Get your first analysis in 20 minutes

Files API

Upload flow for videos

API Reference

Full API specification