> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

Optional: set `transcript_text=true` to return the transcript as a single text string instead of an array of segments.

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

<CardGroup cols={2}>
  <Card title="Content Summary" icon="file-text">
    AI-generated summaries highlighting key points and themes
  </Card>

  <Card title="Entity Extraction" icon="tags">
    Identify people, places, organizations, and concepts mentioned
  </Card>

  <Card title="Topic Analysis" icon="lightbulb">
    Extract main topics, themes, and discussion points
  </Card>

  <Card title="Question Answering" icon="message-question">
    Ask specific questions about the video content
  </Card>
</CardGroup>

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

## Example Usage

### Basic Analysis (Summary Only)

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vidnavigator.com/v1/analyze/video"
  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ"
  }

  response = requests.post(url, headers=headers, json=data)
  analysis = response.json()

  print("Summary:", analysis['data']['transcript_analysis']['summary'])
  print("Key Topics:", analysis['data']['transcript_analysis']['key_topics'])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.vidnavigator.com/v1/analyze/video', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_url: 'https://youtube.com/watch?v=dQw4w9WgXcQ'
    })
  });

  const analysis = await response.json();
  ```
</CodeGroup>

### Analysis with Custom Question

<CodeGroup>
  ```bash cURL theme={null}
  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?"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.vidnavigator.com/v1/analyze/video"
  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "query": "What is the main topic discussed and who are the key speakers?"
  }

  response = requests.post(url, headers=headers, json=data)
  analysis = response.json()

  # Get both summary and question-specific analysis
  summary = analysis['data']['transcript_analysis']['summary']
  question_answer = analysis['data']['transcript_analysis']['question_analysis']
  ```
</CodeGroup>

## Response Example

### Basic Analysis Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Content Research" icon="search">
    Quickly understand video content without watching entire videos
  </Card>

  <Card title="Knowledge Extraction" icon="brain">
    Extract structured data from educational or training content
  </Card>

  <Card title="Content Moderation" icon="shield-check">
    Analyze content for compliance and safety requirements
  </Card>

  <Card title="Learning Platforms" icon="graduation-cap">
    Create summaries and study materials from video lectures
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /analyze/video
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  description: >-
    The VidNavigator Developer API provides programmatic access to video
    analysis, transcription, and search capabilities.


    ## Authentication

    All endpoints require API key authentication via the `X-API-Key` header:

    ```

    X-API-Key: YOUR_API_KEY

    ```


    ## Rate Limits

    Check the documentation for the rate limits for each endpoint.


    ## Error Handling

    The API uses standard HTTP status codes and returns error responses in JSON
    format:

    ```json

    {
      "status": "error",
      "error": "error_type",
      "message": "Human readable error message"
    }

    ```
  version: 1.0.0
  contact:
    name: VidNavigator Support
    url: https://vidnavigator.com/support
    email: support@vidnavigator.com
  license:
    name: Proprietary
    url: https://vidnavigator.com/terms
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Transcripts
    description: Extract transcripts from online videos
  - name: TikTok
    description: Scrape TikTok profile metadata and per-video stats
  - name: Files
    description: Manage uploaded audio/video files
  - name: Analysis
    description: AI-powered content analysis
  - name: Extraction
    description: >-
      Extract structured data from video and file transcripts using custom
      schemas
  - name: Namespaces
    description: Organize uploaded files into namespaces (folders)
  - name: Search
    description: Search videos and files using AI
  - name: System
    description: System health and information
  - name: Tweet Analysis
    description: Extract structured claims and metadata from X/Twitter tweets
paths:
  /analyze/video:
    post:
      tags:
        - Analysis
      summary: Analyze online video
      description: >-
        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


        Optional: set `transcript_text=true` to return the transcript as a
        single text string instead of an array of segments.
      operationId: analyzeVideo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
              properties:
                video_url:
                  type: string
                  format: uri
                  description: URL of the video to analyze
                  example: https://youtube.com/watch?v=dQw4w9WgXcQ
                query:
                  type: string
                  description: Optional question about the video content
                  example: What is the main topic discussed?
                transcript_text:
                  type: boolean
                  default: false
                  description: >-
                    When true, returns the transcript as a single plain-text
                    string instead of an array of segments.
      responses:
        '200':
          description: Video analyzed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    properties:
                      video_info:
                        $ref: '#/components/schemas/VideoInfo'
                      transcript:
                        $ref: '#/components/schemas/TranscriptOutput'
                      transcript_analysis:
                        $ref: '#/components/schemas/AnalysisResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/VideoNotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    VideoInfo:
      type: object
      properties:
        title:
          type: string
          description: Video title
        description:
          type: string
          description: Video description
        thumbnail:
          type: string
          format: uri
          description: Video thumbnail URL
        url:
          type: string
          format: uri
          description: Video URL
        channel:
          type: string
          description: Channel name
        channel_url:
          type: string
          format: uri
          description: Channel URL
        duration:
          type: number
          description: Duration in seconds
        views:
          type: integer
          description: View count
        likes:
          type: integer
          description: Like count
        published_date:
          type: string
          description: Publication date
        keywords:
          type: array
          items:
            type: string
          description: Video keywords/tags
        category:
          type: string
          description: Video category
        available_languages:
          type: array
          items:
            type: string
          description: Available transcript languages
        selected_language:
          type: string
          description: Selected transcript language
        carousel_info:
          $ref: '#/components/schemas/VideoCarouselInfo'
          description: >-
            Present only for carousel posts (e.g., Instagram posts with multiple
            videos)
    TranscriptOutput:
      description: >-
        Transcript output. By default it is an array of segments. When
        `transcript_text=true`, it is returned as a single plain-text string.
      oneOf:
        - type: array
          items:
            $ref: '#/components/schemas/TranscriptSegment'
        - type: string
    AnalysisResult:
      type: object
      properties:
        summary:
          type: string
          description: Content summary
        people:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              context:
                type: string
          description: People mentioned in the content
        places:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              context:
                type: string
          description: Places mentioned in the content
        key_subjects:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              importance:
                type: string
          description: Key subjects/topics discussed
        timestamp:
          type: number
          description: Key moment timestamp (if applicable)
        relevant_text:
          type: string
          description: Key quote from the content (for questions)
        query_answer:
          type: object
          description: Answer to the query (only when query is provided)
          properties:
            answer:
              type: string
            best_segment_index:
              type: integer
            relevant_segments:
              type: array
              items:
                type: string
    VideoCarouselInfo:
      type: object
      description: Carousel information for a single video within a carousel post
      properties:
        total_items:
          type: integer
          description: Total number of items in the carousel (videos + images)
        video_count:
          type: integer
          description: Number of videos in the carousel
        image_count:
          type: integer
          description: Number of images in the carousel
        selected_index:
          type: integer
          description: 1-based index of the selected video
    TranscriptSegment:
      type: object
      properties:
        text:
          type: string
          description: Transcript text for this segment
        start:
          type: number
          description: Start time in seconds
        end:
          type: number
          description: End time in seconds
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    PaymentRequired:
      description: Usage limit exceeded - upgrade required
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - limit_exceeded
              message:
                type: string
    VideoNotFound:
      description: Video not found or transcript unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - video_not_found
                  - transcript_not_available
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - internal_server_error
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key authentication. Include your VidNavigator API key in the
        X-API-Key header.

````