Skip to main content
POST
/
extract
/
video
Extract structured data from online video
curl --request POST \
  --url https://api.vidnavigator.com/v1/extract/video \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --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"
    }
  },
  "what_to_extract": "Extract the main topics and any product names mentioned",
  "include_usage": false
}
'
{
  "status": "success",
  "data": {},
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}
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 transcript and runs AI extraction against your schema
  3. You receive structured JSON matching your schema definition

​
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
You can also send the request body as YAML by setting Content-Type to application/x-yaml or text/yaml.

​
Example Usage

​
Basic Extraction

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"
      }
    }
  }'

​
With Extraction Guidance

Use what_to_extract to provide additional context to the AI about what to focus on:
cURL
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
  }'

​
Response Example

{
  "status": "success",
  "data": {
    "main_topics": ["machine learning", "neural networks", "data preprocessing"],
    "sentiment": "positive",
    "key_takeaway": "Start with clean data before choosing a model architecture"
  },
  "usage": {
    "prompt_tokens": 2150,
    "completion_tokens": 85,
    "total_tokens": 2235
  }
}
The usage field is only included when include_usage=true in the request.

​
Use Cases

Data Pipelines

Build automated pipelines that extract consistent structured data from video content at scale

Content Cataloging

Automatically tag and categorize videos with custom taxonomies

Market Research

Extract product mentions, sentiment, and competitive insights from video reviews

Compliance Monitoring

Pull specific compliance-relevant data points from training or policy videos

Authorizations

​
X-API-Key
string
header
required

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

Body

application/json
​
video_url
string<uri>
required

URL of the video to extract data from

Example:

"https://youtube.com/watch?v=dQw4w9WgXcQ"

​
schema
object
required

Custom extraction schema defining the fields to extract. Max 10 root-level fields, max 3 nesting levels. Each field must have type and description.

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"
  }
}
​
what_to_extract
string

Optional guidance for what to extract from the transcript

Example:

"Extract the main topics and any product names mentioned"

​
include_usage
boolean
default:false

When true, includes token usage statistics in the response

Response

Data extracted successfully

​
status
enum<string>
Available options:
success
​
data
object

Extracted data matching the provided schema. The shape of this object mirrors the input schema fields.

​
usage
object

Token usage statistics. Only present when include_usage=true.