Skip to main content
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"
  }'
{
  "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
}

Authorizations

​
Authorization
string
header
required

API key prefixed with mvra_live_. Create keys at Settings > Developer > API Keys.

Body

application/json
​
video_url
string<uri>
required

URL to the video file hosted in your cloud storage (S3, GCS, etc.).

Example:

"https://your-bucket.s3.amazonaws.com/ad-video.mp4"

​
title
string
required

Title for this analysis.

Required string length: 3 - 100
Example:

"Summer Campaign 2026"

​
brand
string
required

Brand name featured in the video.

Required string length: 2 - 100
Example:

"Acme Corp"

​
product
string
required

Product or service featured in the video.

Required string length: 2 - 100
Example:

"Summer Collection"

​
primary_intent
enum<string>
required

Primary communication intent of the video.

Available options:
Informative,
Persuasive,
Directive,
Expressive,
Transactional,
Appreciative,
Inspirational,
Entertainment
Example:

"Persuasive"

​
goal
string
required

The goal or purpose of the video/advertisement.

Required string length: 10 - 500
Example:

"Drive brand awareness and summer product sales among Gen Z consumers"

​
secondary_intent
enum<string>

Optional secondary communication intent.

Available options:
Informative,
Persuasive,
Directive,
Expressive,
Transactional,
Appreciative,
Inspirational,
Entertainment
Example:

"Inspirational"

​
tertiary_intent
enum<string>

Optional tertiary communication intent.

Available options:
Informative,
Persuasive,
Directive,
Expressive,
Transactional,
Appreciative,
Inspirational,
Entertainment
Example:

"Entertainment"

​
chunk_duration
integer
default:2

Duration in seconds for each analysis chunk (default: 2).

Required range: 1 <= x <= 10
Example:

2

​
frames_per_chunk
integer
default:4

Number of frames to analyze per chunk (default: 4).

Required range: 1 <= x <= 10
Example:

4

Response

Video analysis started. Poll the returned ID for results.

​
id
string

Unique identifier for the video analysis.

Example:

"cly1abc2d0001abcdef123456"

​
object
enum<string>
Available options:
video_analysis
Example:

"video_analysis"

​
status
enum<string>

Current processing status.

Available options:
pending,
generating,
completed,
failed
Example:

"pending"

​
created_at
integer

Unix timestamp when the analysis was created.

Example:

1706380800

​
video_url
string
Example:

"https://your-bucket.s3.amazonaws.com/ad-video.mp4"

​
title
string
Example:

"Summer Campaign 2026"

​
brand
string
Example:

"Acme Corp"

​
product
string
Example:

"Summer Collection"

​
primary_intent
string
Example:

"Persuasive"

​
secondary_intent
string | null
​
tertiary_intent
string | null
​
goal
string
​
chunk_duration
integer
Example:

2

​
frames_per_chunk
integer
Example:

4