Extract Data from Video

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

OverviewCopy Anchor Link

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 WorksCopy Anchor Link

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 RulesCopy Anchor Link

• 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

Automatic TranscriptionCopy Anchor Link

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.

Synchronous or async?Copy Anchor Link

The extraction itself is fast; the speech-to-text step in front of it is what takes time on long videos. This endpoint therefore comes in two modes, with the same request body and the same result:

Example UsageCopy Anchor Link

Basic ExtractionCopy Anchor Link

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 GuidanceCopy Anchor Link

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

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-TranscriptionCopy Anchor Link

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

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 ExampleCopy Anchor Link

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

BillingCopy Anchor Link

• 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
• Set include_usage: true to receive a usage block with the per-charge breakdown (the analysis_request entry carries a nested tokens object)
• The async mode is billed exactly the same way
• A video_too_long rejection on the synchronous endpoint still bills the metadata fetch that read the duration (standard_request or residential_request, not refunded), but no transcription_hour and no analysis_request

Error ResponsesCopy Anchor Link

See Errors for the full list.

Use CasesCopy Anchor Link

API referenceCopy Anchor Link

curl -X POST 'https://api.vidnavigator.com/v1/extract/video' \  -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"    }  }}'

{  "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    }  },  "file_info": {    "id": "string",    "name": "string",    "size": 0,    "type": "string",    "duration": 0,    "status": "pending",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "original_file_date": "2019-08-24T14:15:22Z",    "has_transcript": true,    "error_message": "string",    "namespace_ids": [      "string"    ],    "namespaces": [      {        "id": "string",        "name": "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    }  }}