Skip to Content

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.

POST
/analyze/video

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 as POST /watch returns, and frames_analyzed.
  • A video without a transcript is analyzed from its scenes, and transcript_error says why there is no transcript. A video whose picture cannot be read is analyzed from its transcript, and scenes_error says 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_error is video_too_long. Use POST /analyze/video/async for 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
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

Authorization

ApiKeyAuth
headerX-API-Key<token>

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Request Body

application/json
  1. body
video_url*string

URL of the video to analyze

Formaturi
query?string

Optional question about the video content

include_scenes?boolean

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

Defaultfalse
transcript_text?boolean

When true, returns the transcript as a single plain-text string instead of an array of segments.

Defaultfalse
include_usage?boolean

When true, the response includes the usage block of this request.

Defaultfalse

Response Body

Video analyzed successfully

application/json
  1. response
status?"success"
Value in"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.

Example Request
curl -X POST 'https://api.vidnavigator.com/v1/analyze/video' \  -H 'Content-Type: application/json' \  -d '{  "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ"}'
Example Response
{  "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    }  }}

On this page