Analyze Video
Analyze an online video and return comprehensive analysis results with intelligent caching.
Behavior:
- If no query provided: Returns summary analysis (cached if available)
- If query provided: Returns both summary (from cache if available) and fresh question analysis
Caching:
- Summary analyses are cached and reused
- Question/query analyses are not cached (always fresh)
- Transcripts are cached for optimization
Set include_usage=true to receive the usage block, with the request's token counts.
Optional: set transcript_text=true to return the transcript as a single text string instead of an array of segments.
Scenes: set include_scenes=true to also read what the video shows. The analysis is then made from the transcript and the scenes together. With a query, the picture is also looked at a second time with the question in mind, and what it shows for it is read with the scenes; the scenes returned stay the same for every question. data also holds scenes and frames_analyzed, as on POST /watch. When the picture cannot be read, the analysis is made from the transcript alone and scenes_error says why. A video without a transcript is analyzed from its scenes, and transcript_error says why the transcript is missing. The segments an answer refers to are then counted among the transcript segments and the scenes together, in chronological order, a scene before a segment that starts at the same second: use timestamp to locate the moment.
Long videos: this endpoint is synchronous. With include_scenes on a video longer than ~10 minutes, use POST /analyze/video/async.
Get comprehensive AI-powered analysis of online videos including summaries, key insights, and structured data extraction.
Overview
Transform any online video into structured insights with our advanced AI analysis. Extract summaries, identify people and places, generate key topics, and ask specific questions about the content.
Analysis Capabilities
Content Summary
AI-generated summaries highlighting key points and themes
Entity Extraction
Identify people, places, organizations, and concepts mentioned
Topic Analysis
Extract main topics, themes, and discussion points
Question Answering
Ask specific questions about the video content
Intelligent Caching
- Summary analyses are cached and reused for efficiency
- Question/query analyses are always fresh and never cached
- Transcripts are cached to optimize performance
Billing
Analysis consumes analysis_request units based on context size. One unit covers up to 15,000 total tokens, and longer contexts are billed with ceil(total_tokens / 15000). For example, an analysis that uses 17,000 total tokens consumes 2 analysis_request units. One unit is charged up front as a credit gate; additional units are topped up at the end if the LLM call exceeded 15,000 tokens.
When the transcript isn't cached, one additional residential_request or standard_request is charged for the fetch (residential for YouTube/Instagram/Facebook-watch/Rumble, standard otherwise).
Set include_usage: true to receive a usage block with the per-charge breakdown — the consolidated analysis_request entry carries a nested tokens object with prompt_tokens / completion_tokens / total_tokens.
Use what the video shows
By default the analysis reads the transcript. With include_scenes: true it also reads what the video shows — its scenes, with the text readable on screen — and uses both. Ask for it when the answer may be on screen rather than said (the quantities of a recipe, a price, a slide, a caption), or when the video has little or no speech. With a query, the picture is also looked at a second time with the question in mind; the scenes returned stay the same for every question.
- The response then carries
scenes, the same objects asPOST /watchreturns, andframes_analyzed. - A video without a transcript is analyzed from its scenes, and
transcript_errorsays why there is no transcript. A video whose picture cannot be read is analyzed from its transcript, andscenes_errorsays why. - On this synchronous endpoint the picture of a video longer than 10 minutes is not read: the analysis is made from the transcript and
scenes_errorisvideo_too_long. UsePOST /analyze/video/asyncfor those. - The frames are charged on top of the analysis: 1 credit per 2,000 frames analyzed, with at least 667 frames per hour of video. See Usage & costs.
curl -X POST "https://api.vidnavigator.com/v1/analyze/video" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://www.dailymotion.com/video/x84243e",
"query": "What are the ingredients and their quantities?",
"include_scenes": true
}'{
"status": "success",
"data": {
"video_info": { "title": "PATÊ DE FRANGO CREMOSO", "duration": 79 },
"transcript": [{ "text": "Música", "start": 0.0, "end": 4.0 }],
"transcript_analysis": {
"summary": "The video shows how to make a creamy chicken pâté...",
"query_answer": {
"answer": "Shredded cooked chicken 500 g; mayonnaise 300 g; requeijão 250 g; 2 grated carrots; corn 250 g; green olives 250 g; herbs to taste."
}
},
"scenes": [
{
"start": 2.0,
"end": 6.0,
"description": "A hand tips shredded chicken into a glass bowl.",
"on_screen_text": "500 g FRANGO DESFIADO COZIDO"
}
],
"frames_analyzed": 30
}
}This video only has music: without include_scenes, the same question gets no answer.
Example Usage
Basic Analysis (Summary Only)
curl -X POST "https://api.vidnavigator.com/v1/analyze/video" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ"
}'Analysis with Custom Question
curl -X POST "https://api.vidnavigator.com/v1/analyze/video" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"query": "What is the main topic discussed and who are the key speakers?"
}'Response Example
Basic Analysis Response
{
"status": "success",
"data": {
"video_info": {
"title": "How to Build a Startup",
"description": "A comprehensive guide to building a startup from scratch.",
"thumbnail": "https://example.com/thumbnail.jpg",
"url": "https://youtube.com/watch?v=example123",
"channel": "TechTalks",
"duration": 1530.0,
"views": 150000,
"likes": 4500,
"published_date": "2023-05-10",
"keywords": ["startup", "entrepreneurship", "business"],
"category": "Education"
},
"transcript": [
{
"text": "Welcome to today's discussion on building startups...",
"start": 0.0,
"end": 4.2
}
],
"transcript_analysis": {
"summary": "This video covers essential startup building strategies including market validation, team building, and funding approaches. The speaker emphasizes the importance of customer feedback and iterative development.",
"key_topics": [
"Market validation",
"Team building",
"Funding strategies",
"Customer feedback",
"Product development"
],
"people": [
{
"name": "Sarah Johnson",
"context": "CEO and founder discussing her startup journey"
}
],
"places": [
{
"name": "Silicon Valley",
"context": "Mentioned as a startup hub"
}
],
"sentiment": "positive",
"category": "business_education"
}
}
}Analysis with Question Response
{
"status": "success",
"data": {
"transcript_analysis": {
"summary": "...",
"question_analysis": {
"question": "What is the main topic discussed and who are the key speakers?",
"answer": "The main topic is startup building strategies with focus on market validation and customer development. The key speaker is Sarah Johnson, CEO of TechCorp, who shares insights from her 5-year entrepreneurial journey.",
"confidence": 0.92,
"relevant_segments": [
{
"text": "Hi, I'm Sarah Johnson, CEO of TechCorp...",
"start": 15.0,
"end": 25.0
}
]
}
}
}
}Use Cases
Content Research
Quickly understand video content without watching entire videos
Knowledge Extraction
Extract structured data from educational or training content
Content Moderation
Analyze content for compliance and safety requirements
Learning Platforms
Create summaries and study materials from video lectures
API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
application/json- body
video_url*stringURL of the video to analyze
uriquery?stringOptional question about the video content
include_scenes?booleanWhen true, the scenes of the video (what it shows, with the text readable on screen) are read as well, as POST /watch does, and used together with the transcript.
falsetranscript_text?booleanWhen true, returns the transcript as a single plain-text string instead of an array of segments.
falseinclude_usage?booleanWhen true, the response includes the usage block of this request.
falseVideo analyzed successfully
application/json- response
status?"success""success"data?An analyzed video: its metadata, its transcript, its analysis and, when include_scenes=true, its scenes.
usage?Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.
For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.
curl -X POST 'https://api.vidnavigator.com/v1/analyze/video' \ -H 'Content-Type: application/json' \ -d '{ "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'{ "status": "success", "data": { "video_info": { "title": "string", "description": "string", "thumbnail": "http://example.com", "url": "http://example.com", "channel": "string", "channel_url": "http://example.com", "duration": 0, "views": 0, "likes": 0, "published_date": "string", "keywords": [ "string" ], "category": "string", "available_languages": [ "string" ], "selected_language": "string", "carousel_info": { "total_items": 0, "video_count": 0, "image_count": 0, "selected_index": 0 } }, "transcript": [ { "text": "string", "start": 0, "end": 0 } ], "transcript_error": { "error": "transcript_not_available", "message": "string" }, "transcript_analysis": { "summary": "string", "people": [ { "name": "string", "context": "string" } ], "places": [ { "name": "string", "context": "string" } ], "key_subjects": [ { "name": "string", "description": "string", "importance": "string" } ], "timestamp": 0, "relevant_text": "string", "query_answer": { "answer": "string", "best_segment_index": 0, "relevant_segments": [ "string" ] } }, "scenes": [ { "start": 4, "end": 12, "description": "A presenter stands in front of a world map and points at Europe.", "on_screen_text": "BREAKING NEWS" } ], "frames_analyzed": 23, "scenes_error": { "error": "frames_not_available", "message": "string" } }, "usage": { "charges": [ { "service_type": "standard_request", "quantity": 0, "credits": 0, "waived": true, "credits_saved": 0, "tokens": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 } } ], "total_credits": 0, "waived": { "credits_saved": 0 } }}