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

# Extract Data from Video

> Extract structured data from an online video's transcript using a custom schema.

Provide a `video_url` and a JSON `schema` describing the fields to extract. Optionally include `what_to_extract` to guide the extraction.

**Auto-transcription:** For non-YouTube videos without an existing transcript (e.g. Instagram, TikTok, Facebook), the API automatically transcribes the video audio when `transcribe` is `true` (the default). This uses speech-to-text credits (`video_uploads` quota). YouTube videos rely on platform captions and cannot be auto-transcribed. Set `transcribe=false` to disable this behavior.

**Schema format:** Each field must have `type` and `description`. Supported types: `String`, `Number`, `Boolean`, `Integer`, `Object`, `Array`, `Enum`. Max 10 root fields, max 3 nesting levels.

**Content-Type:** Accepts `application/json` or YAML (`application/x-yaml`, `text/yaml`).

**Token usage:** Set `include_usage=true` to include prompt/completion token counts in the response.

**Billing:** Each extraction consumes at least 1 analysis credit. For longer transcripts, billing scales as `ceil(total_tokens / 15000)` credits. If auto-transcription is triggered, speech-to-text hours are also charged based on video duration. All charges are reverted if the request fails.

Extract structured data from an online video's transcript using a custom schema you define.

## Overview

The extraction endpoint lets you pull structured, typed data from any video transcript by providing a JSON schema describing the fields you need. This is ideal for building automated pipelines that need consistent, machine-readable output from video content.

### How It Works

1. Provide a `video_url` and a `schema` defining the fields to extract
2. VidNavigator fetches the platform transcript when available
3. For supported non-YouTube sources, it can auto-transcribe audio when no transcript exists
4. VidNavigator runs AI extraction against your schema
5. You receive structured JSON matching your schema definition, plus `video_info`

### Schema Rules

* Each field must have `type` and `description`
* Supported types: `String`, `Number`, `Boolean`, `Integer`, `Object`, `Array`, `Enum`
* Maximum **10 root-level fields**
* Maximum **3 nesting levels**

<Tip>
  You can also send the request body as YAML by setting `Content-Type` to `application/x-yaml` or `text/yaml`.
</Tip>

### Automatic Transcription

The `transcribe` parameter controls whether VidNavigator should automatically fall back to speech-to-text when a transcript is not available.

* `transcribe=true` by default
* applies to non-YouTube videos only
* useful for platforms like Instagram, TikTok, Facebook, X, and similar sources
* YouTube extraction relies on platform captions and does not support speech-to-text fallback through this endpoint

If you set `transcribe=false`, the request will fail when no transcript is available instead of triggering speech-to-text processing.

## Example Usage

### Basic Extraction

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.vidnavigator.com/v1/extract/video" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "schema": {
        "main_topics": {
          "type": "Array",
          "description": "List of main topics discussed",
          "items": { "type": "String", "description": "A topic" }
        },
        "sentiment": {
          "type": "Enum",
          "description": "Overall sentiment of the video",
          "enum": ["positive", "negative", "neutral"]
        },
        "key_takeaway": {
          "type": "String",
          "description": "The single most important takeaway"
        }
      }
    }'
  ```

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

  url = "https://api.vidnavigator.com/v1/extract/video"
  headers = {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "schema": {
          "main_topics": {
              "type": "Array",
              "description": "List of main topics discussed",
              "items": {"type": "String", "description": "A topic"}
          },
          "sentiment": {
              "type": "Enum",
              "description": "Overall sentiment of the video",
              "enum": ["positive", "negative", "neutral"]
          },
          "key_takeaway": {
              "type": "String",
              "description": "The single most important takeaway"
          }
      }
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(result["data"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.vidnavigator.com/v1/extract/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',
      schema: {
        main_topics: {
          type: 'Array',
          description: 'List of main topics discussed',
          items: { type: 'String', description: 'A topic' }
        },
        sentiment: {
          type: 'Enum',
          description: 'Overall sentiment of the video',
          enum: ['positive', 'negative', 'neutral']
        },
        key_takeaway: {
          type: 'String',
          description: 'The single most important takeaway'
        }
      }
    })
  });

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

### With Extraction Guidance

Use `what_to_extract` to provide additional context to the AI about what to focus on:

```bash cURL theme={null}
curl -X POST "https://api.vidnavigator.com/v1/extract/video" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "what_to_extract": "Focus on product names and pricing mentioned in the video",
    "schema": {
      "products": {
        "type": "Array",
        "description": "Products mentioned in the video",
        "items": {
          "type": "Object",
          "description": "A product",
          "properties": {
            "name": { "type": "String", "description": "Product name" },
            "price": { "type": "String", "description": "Price if mentioned" }
          }
        }
      }
    },
    "include_usage": true
  }'
```

### Disable Auto-Transcription

Use `transcribe=false` when you want extraction to run only if a platform transcript already exists:

```bash cURL theme={null}
curl -X POST "https://api.vidnavigator.com/v1/extract/video" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.instagram.com/reel/example/",
    "transcribe": false,
    "schema": {
      "main_claim": {
        "type": "String",
        "description": "Main claim made in the video"
      }
    }
  }'
```

## Response Example

```json theme={null}
{
  "status": "success",
  "data": {
    "main_topics": ["machine learning", "neural networks", "data preprocessing"],
    "sentiment": "positive",
    "key_takeaway": "Start with clean data before choosing a model architecture"
  },
  "video_info": {
    "title": "Machine Learning Fundamentals",
    "description": "An introduction to practical machine learning workflows.",
    "thumbnail": "https://example.com/thumbnail.jpg",
    "url": "https://youtube.com/watch?v=example123",
    "channel": "AI Academy",
    "duration": 4520.0,
    "views": 152340,
    "likes": 8100,
    "published_date": "2026-03-05",
    "keywords": ["machine learning", "ai", "data science"],
    "category": "Education"
  },
  "usage": {
    "prompt_tokens": 2150,
    "completion_tokens": 85,
    "total_tokens": 2235
  }
}
```

<Note>
  The `usage` field is only included when `include_usage=true` in the request. `video_info` is included in the response metadata.
</Note>

## Billing

* AI extraction consumes `analysis_request` units in blocks of **15,000 total tokens**
* Formula: `ceil(total_tokens / 15000)`
* Examples:
  * `14,000` tokens -> `1` `analysis_request` unit
  * `17,000` tokens -> `2` `analysis_request` units
  * `31,000` tokens -> `3` `analysis_request` units
* If `transcribe=true` triggers speech-to-text fallback, speech-to-text is charged separately as `transcription_hour` usage based on **video/audio duration**
* Failed requests are not charged

## Use Cases

<CardGroup cols={2}>
  <Card title="Data Pipelines" icon="pipe-section">
    Build automated pipelines that extract consistent structured data from video content at scale
  </Card>

  <Card title="Content Cataloging" icon="tags">
    Automatically tag and categorize videos with custom taxonomies
  </Card>

  <Card title="Market Research" icon="chart-line">
    Extract product mentions, sentiment, and competitive insights from video reviews
  </Card>

  <Card title="Compliance Monitoring" icon="shield-check">
    Pull specific compliance-relevant data points from training or policy videos
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /extract/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:
  /extract/video:
    post:
      tags:
        - Extraction
      summary: Extract structured data from online video
      description: >-
        Extract structured data from an online video's transcript using a custom
        schema.


        Provide a `video_url` and a JSON `schema` describing the fields to
        extract. Optionally include `what_to_extract` to guide the extraction.


        **Auto-transcription:** For non-YouTube videos without an existing
        transcript (e.g. Instagram, TikTok, Facebook), the API automatically
        transcribes the video audio when `transcribe` is `true` (the default).
        This uses speech-to-text credits (`video_uploads` quota). YouTube videos
        rely on platform captions and cannot be auto-transcribed. Set
        `transcribe=false` to disable this behavior.


        **Schema format:** Each field must have `type` and `description`.
        Supported types: `String`, `Number`, `Boolean`, `Integer`, `Object`,
        `Array`, `Enum`. Max 10 root fields, max 3 nesting levels.


        **Content-Type:** Accepts `application/json` or YAML
        (`application/x-yaml`, `text/yaml`).


        **Token usage:** Set `include_usage=true` to include prompt/completion
        token counts in the response.


        **Billing:** Each extraction consumes at least 1 analysis credit. For
        longer transcripts, billing scales as `ceil(total_tokens / 15000)`
        credits. If auto-transcription is triggered, speech-to-text hours are
        also charged based on video duration. All charges are reverted if the
        request fails.
      operationId: extractVideoData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - video_url
                - schema
              properties:
                video_url:
                  type: string
                  format: uri
                  description: URL of the video to extract data from
                  example: https://youtube.com/watch?v=dQw4w9WgXcQ
                schema:
                  $ref: '#/components/schemas/ExtractionSchema'
                what_to_extract:
                  type: string
                  description: Optional guidance for what to extract from the transcript
                  example: Extract the main topics and any product names mentioned
                transcribe:
                  type: boolean
                  default: true
                  description: >-
                    When true, automatically transcribes the video audio if no
                    platform transcript is available. Applies to non-YouTube
                    videos only (Instagram, TikTok, Facebook, X, etc.). Uses
                    speech-to-text credits based on video duration.
                include_usage:
                  type: boolean
                  default: false
                  description: When true, includes token usage statistics in the response
      responses:
        '200':
          description: Data extracted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractionResponse'
        '400':
          description: Bad request - missing parameters, invalid schema, or input too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - missing_parameter
                      - request_body_required
                      - invalid_schema
                      - input_too_large
                  message:
                    type: string
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          description: >-
            Video or transcript not found. Returned when no transcript is
            available and auto-transcription is disabled or not supported
            (YouTube).
          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
        '500':
          description: Internal server error, including transcription failures
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - internal_server_error
                      - extraction_failed
                      - transcription_failed
                  message:
                    type: string
        '503':
          $ref: '#/components/responses/SystemOverload'
components:
  schemas:
    ExtractionSchema:
      type: object
      description: >-
        Custom extraction schema defining the fields to extract. Max 10
        root-level fields, max 3 nesting levels. Each field must have `type` and
        `description`.
      additionalProperties:
        type: object
        required:
          - type
          - description
        properties:
          type:
            type: string
            enum:
              - String
              - Number
              - Boolean
              - Integer
              - Object
              - Array
              - Enum
            description: The data type of the field
          description:
            type: string
            description: Description of what this field should contain
          properties:
            type: object
            description: Sub-fields for Object type
          items:
            type: object
            description: Item schema for Array type
          enum:
            type: array
            items:
              type: string
            description: Allowed values for Enum type
      example:
        main_topics:
          type: Array
          description: List of main topics discussed
          items:
            type: String
            description: A topic
        sentiment:
          type: Enum
          description: Overall sentiment of the video
          enum:
            - positive
            - negative
            - neutral
        key_takeaway:
          type: String
          description: The single most important takeaway
    ExtractionResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
        data:
          type: object
          description: >-
            Extracted data matching the provided schema. The shape of this
            object mirrors the input schema fields.
        video_info:
          allOf:
            - $ref: '#/components/schemas/VideoInfo'
          description: >-
            Video metadata (title, channel, duration, views, etc.). Only present
            for /extract/video requests.
        file_info:
          allOf:
            - $ref: '#/components/schemas/FileInfo'
          description: >-
            File metadata (name, size, type, duration, etc.). Only present for
            /extract/file requests.
        usage:
          type: object
          description: Token usage statistics. Only present when include_usage=true.
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    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)
    FileInfo:
      type: object
      properties:
        id:
          type: string
          description: Unique file identifier
        name:
          type: string
          description: File name
        size:
          type: integer
          description: File size in bytes
        type:
          type: string
          description: MIME type
        duration:
          type: number
          description: Duration in seconds
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
            - cancelled
          description: Processing status
        created_at:
          type: string
          format: date-time
          description: Upload timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        original_file_date:
          type: string
          format: date-time
          description: Original file creation date
        has_transcript:
          type: boolean
          description: Whether transcript is available
        error_message:
          type: string
          description: Error message if processing failed
        namespace_ids:
          type: array
          items:
            type: string
          description: IDs of the namespaces this file belongs to
        namespaces:
          type: array
          items:
            $ref: '#/components/schemas/NamespaceRef'
          description: Resolved namespaces this file belongs to (with names)
    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
    NamespaceRef:
      type: object
      description: Resolved namespace reference with ID and display name
      properties:
        id:
          type: string
          description: Namespace identifier
        name:
          type: string
          description: Namespace display name
  responses:
    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
    SystemOverload:
      description: System is temporarily overloaded
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - system_overload
              message:
                type: string
              retry_after_seconds:
                type: integer
                description: Recommended number of seconds to wait before retrying
              charge_user:
                type: boolean
                description: Always false for overload errors — the request was not billed
  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.

````