Video Analysis

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:

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).

Create the analysis

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

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.

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")

async function waitForCompletion(analysisId, maxWaitMinutes = 15) {
  for (let i = 0; i < maxWaitMinutes * 4; i++) {
    const resp = await fetch(
      `https://app.mavera.io/api/v1/video-analyses/${analysisId}`,
      { headers: { Authorization: "Bearer mvra_live_your_key_here" } }
    );
    const data = await resp.json();
    if (data.error) throw new Error(data.error.message);
    if (data.status === "COMPLETED") return data;
    await new Promise((r) => setTimeout(r, 15000));
  }
  throw new Error("Analysis did not complete");
}

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", ""))

const resp = await fetch(
  `https://app.mavera.io/api/v1/video-analyses/${analysisId}/chat`,
  {
    method: "POST",
    headers: {
      Authorization: "Bearer mvra_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      message: "What are the weakest moments and how can I improve them?",
    }),
  }
);
const data = await resp.json();
if (!data.error) console.log(data.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 Length	Approximate Cost
< 30 seconds	100-150 credits
30s - 1 min	150-250 credits
1-3 minutes	250-400 credits
3+ minutes	400+ credits

Best Practices

Use short clips for iteration

Start with 15–60 second clips to iterate quickly. Longer videos use more credits and take longer to process.

Provide context (goal, brand, product)

The goal, brand, and primary_intent parameters improve relevance of metrics and recommendations.

Adjust chunk_duration

Shorter chunks (e.g. 3–5 seconds) give finer granularity; longer chunks (e.g. 10 seconds) reduce processing time.

Compare creatives

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

Getting Started

Core Concepts

Features

SDKs & Libraries

Video Analysis

Overview

Before You Start

Key Metrics

Emotional

Cognitive

Behavioral

Technical

Creating an Analysis

Retrieving Results

Polling Pattern

Reading Metrics

Chat About Results

Response Format

Credit Costs

Best Practices

Tutorial

Quickstart

Files API

API Reference

​Overview

​Before You Start

​Key Metrics

Emotional

Cognitive

Behavioral

Technical

​Creating an Analysis

​Retrieving Results

​Polling Pattern

​Reading Metrics

​Chat About Results

​Response Format

​Credit Costs

​Best Practices

Tutorial

Quickstart

Files API

API Reference

Overview

Before You Start

Key Metrics

Creating an Analysis

Retrieving Results

Polling Pattern

Reading Metrics

Chat About Results

Response Format

Credit Costs

Best Practices