Video Analysis
Create a video analysis
Submit a video for comprehensive AI-powered analysis. The video will be processed in the background, analyzing emotional, cognitive, behavioral, and technical metrics.
Processing: Analysis is performed asynchronously. Processing duration scales with video length.
Video Requirements:
- Host your video on cloud storage (S3, GCS, etc.) and provide a publicly accessible URL
- Supported formats: MP4, WebM, MOV, AVI
- Maximum duration: Based on your subscription’s included minutes
Polling for Results: Use GET /video-analyses/{id} to check status and retrieve results when complete.
POST
/
video-analyses
cURL
curl -X POST https://app.mavera.io/api/v1/video-analyses \
-H "Authorization: Bearer mvra_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"goal": "Drive brand awareness and summer product sales among Gen Z consumers"
}'import requests
import time
headers = {"Authorization": "Bearer mvra_live_your_key_here"}
# 1. Submit video for analysis
response = requests.post(
"https://app.mavera.io/api/v1/video-analyses",
headers=headers,
json={
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"goal": "Drive brand awareness among Gen Z consumers"
}
)
analysis_id = response.json()["id"]
print(f"Analysis started: {analysis_id}")
# 2. Poll for completion
while True:
status_response = requests.get(
f"https://app.mavera.io/api/v1/video-analyses/{analysis_id}",
headers=headers
)
status = status_response.json()["status"]
if status == "completed":
results = status_response.json()["results"]
print(f"Ad Effectiveness Score: {results['metrics']['ad_effectiveness']['score']}/10")
break
elif status == "failed":
print(f"Analysis failed: {status_response.json().get('error')}")
break
print(f"Status: {status}, waiting...")
time.sleep(10)const headers = { Authorization: "Bearer mvra_live_your_key_here" };
// 1. Submit video for analysis
const response = await fetch("https://app.mavera.io/api/v1/video-analyses", {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({
video_url: "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
title: "Summer Campaign 2026",
brand: "Acme Corp",
product: "Summer Collection",
primary_intent: "Persuasive",
goal: "Drive brand awareness among Gen Z consumers"
})
});
const { id: analysisId } = await response.json();
console.log("Analysis started:", analysisId);
// 2. Poll for completion
const pollForResults = async () => {
const statusRes = await fetch(
`https://app.mavera.io/api/v1/video-analyses/${analysisId}`,
{ headers }
);
const data = await statusRes.json();
if (data.status === "completed") {
console.log("Ad Effectiveness:", data.results.metrics.ad_effectiveness.score);
return data;
} else if (data.status === "failed") {
throw new Error(data.error);
}
await new Promise(r => setTimeout(r, 10000));
return pollForResults();
};
const results = await pollForResults();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.mavera.io/api/v1/video-analyses"
payload := strings.NewReader("{\n \"video_url\": \"https://your-bucket.s3.amazonaws.com/ad-video.mp4\",\n \"title\": \"Summer Campaign 2026\",\n \"brand\": \"Acme Corp\",\n \"product\": \"Summer Collection\",\n \"primary_intent\": \"Persuasive\",\n \"goal\": \"Drive brand awareness and summer product sales among Gen Z consumers\",\n \"secondary_intent\": \"Inspirational\",\n \"tertiary_intent\": \"Entertainment\",\n \"chunk_duration\": 2,\n \"frames_per_chunk\": 4\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "cly1abc2d0001abcdef123456",
"object": "video_analysis",
"status": "pending",
"created_at": 1706380800,
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"secondary_intent": "<string>",
"tertiary_intent": "<string>",
"goal": "<string>",
"chunk_duration": 2,
"frames_per_chunk": 4
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}Authorizations
API key prefixed with mvra_live_. Create keys at Settings > Developer > API Keys.
Body
application/json
URL to the video file hosted in your cloud storage (S3, GCS, etc.).
Example:
"https://your-bucket.s3.amazonaws.com/ad-video.mp4"
Title for this analysis.
Required string length:
3 - 100Example:
"Summer Campaign 2026"
Brand name featured in the video.
Required string length:
2 - 100Example:
"Acme Corp"
Product or service featured in the video.
Required string length:
2 - 100Example:
"Summer Collection"
Primary communication intent of the video.
Available options:
Informative, Persuasive, Directive, Expressive, Transactional, Appreciative, Inspirational, Entertainment Example:
"Persuasive"
The goal or purpose of the video/advertisement.
Required string length:
10 - 500Example:
"Drive brand awareness and summer product sales among Gen Z consumers"
Optional secondary communication intent.
Available options:
Informative, Persuasive, Directive, Expressive, Transactional, Appreciative, Inspirational, Entertainment Example:
"Inspirational"
Optional tertiary communication intent.
Available options:
Informative, Persuasive, Directive, Expressive, Transactional, Appreciative, Inspirational, Entertainment Example:
"Entertainment"
Duration in seconds for each analysis chunk (default: 2).
Required range:
1 <= x <= 10Example:
2
Number of frames to analyze per chunk (default: 4).
Required range:
1 <= x <= 10Example:
4
Response
Video analysis started. Poll the returned ID for results.
Unique identifier for the video analysis.
Example:
"cly1abc2d0001abcdef123456"
Available options:
video_analysis Example:
"video_analysis"
Current processing status.
Available options:
pending, generating, completed, failed Example:
"pending"
Unix timestamp when the analysis was created.
Example:
1706380800
Example:
"https://your-bucket.s3.amazonaws.com/ad-video.mp4"
Example:
"Summer Campaign 2026"
Example:
"Acme Corp"
Example:
"Summer Collection"
Example:
"Persuasive"
Example:
2
Example:
4
⌘I
cURL
curl -X POST https://app.mavera.io/api/v1/video-analyses \
-H "Authorization: Bearer mvra_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"goal": "Drive brand awareness and summer product sales among Gen Z consumers"
}'import requests
import time
headers = {"Authorization": "Bearer mvra_live_your_key_here"}
# 1. Submit video for analysis
response = requests.post(
"https://app.mavera.io/api/v1/video-analyses",
headers=headers,
json={
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"goal": "Drive brand awareness among Gen Z consumers"
}
)
analysis_id = response.json()["id"]
print(f"Analysis started: {analysis_id}")
# 2. Poll for completion
while True:
status_response = requests.get(
f"https://app.mavera.io/api/v1/video-analyses/{analysis_id}",
headers=headers
)
status = status_response.json()["status"]
if status == "completed":
results = status_response.json()["results"]
print(f"Ad Effectiveness Score: {results['metrics']['ad_effectiveness']['score']}/10")
break
elif status == "failed":
print(f"Analysis failed: {status_response.json().get('error')}")
break
print(f"Status: {status}, waiting...")
time.sleep(10)const headers = { Authorization: "Bearer mvra_live_your_key_here" };
// 1. Submit video for analysis
const response = await fetch("https://app.mavera.io/api/v1/video-analyses", {
method: "POST",
headers: { ...headers, "Content-Type": "application/json" },
body: JSON.stringify({
video_url: "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
title: "Summer Campaign 2026",
brand: "Acme Corp",
product: "Summer Collection",
primary_intent: "Persuasive",
goal: "Drive brand awareness among Gen Z consumers"
})
});
const { id: analysisId } = await response.json();
console.log("Analysis started:", analysisId);
// 2. Poll for completion
const pollForResults = async () => {
const statusRes = await fetch(
`https://app.mavera.io/api/v1/video-analyses/${analysisId}`,
{ headers }
);
const data = await statusRes.json();
if (data.status === "completed") {
console.log("Ad Effectiveness:", data.results.metrics.ad_effectiveness.score);
return data;
} else if (data.status === "failed") {
throw new Error(data.error);
}
await new Promise(r => setTimeout(r, 10000));
return pollForResults();
};
const results = await pollForResults();package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.mavera.io/api/v1/video-analyses"
payload := strings.NewReader("{\n \"video_url\": \"https://your-bucket.s3.amazonaws.com/ad-video.mp4\",\n \"title\": \"Summer Campaign 2026\",\n \"brand\": \"Acme Corp\",\n \"product\": \"Summer Collection\",\n \"primary_intent\": \"Persuasive\",\n \"goal\": \"Drive brand awareness and summer product sales among Gen Z consumers\",\n \"secondary_intent\": \"Inspirational\",\n \"tertiary_intent\": \"Entertainment\",\n \"chunk_duration\": 2,\n \"frames_per_chunk\": 4\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "cly1abc2d0001abcdef123456",
"object": "video_analysis",
"status": "pending",
"created_at": 1706380800,
"video_url": "https://your-bucket.s3.amazonaws.com/ad-video.mp4",
"title": "Summer Campaign 2026",
"brand": "Acme Corp",
"product": "Summer Collection",
"primary_intent": "Persuasive",
"secondary_intent": "<string>",
"tertiary_intent": "<string>",
"goal": "<string>",
"chunk_duration": 2,
"frames_per_chunk": 4
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}{
"error": {
"message": "Invalid API key.",
"type": "authentication_error",
"code": "invalid_api_key",
"param": null
}
}