Extract Data from File

Extract structured data from an uploaded file's transcript using a custom schema.

Provide a file_id and a schema describing the fields to extract. The file must be processed and have a transcript available. Optionally include what_to_extract to guide the extraction.

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, YAML (application/yaml, application/x-yaml, text/yaml), or multipart/form-data. For multipart requests, send file_id as a form field and schema as either a JSON/YAML form value or an uploaded JSON/YAML file. If the uploaded schema file contains a full request body with a nested schema property, the nested schema is used and the form file_id takes precedence.

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

Extract structured data from an uploaded file's transcript using a custom schema you define.

Overview

Extract structured data from files you have previously uploaded to your VidNavigator library. The file must be fully processed and have a transcript available.

How It Works

Provide a file_id and a schema describing the structured fields you want
VidNavigator reads the transcript from the uploaded file
VidNavigator runs AI extraction against your schema
You receive structured JSON matching your schema definition, plus file_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

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

This endpoint does not support a transcribe parameter. It works only on files that already have a transcript available.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/extract/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_abc123",
    "schema": {
      "action_items": {
        "type": "Array",
        "description": "Action items and tasks mentioned in the meeting",
        "items": {
          "type": "Object",
          "description": "An action item",
          "properties": {
            "task": { "type": "String", "description": "The task description" },
            "assignee": { "type": "String", "description": "Person assigned" },
            "deadline": { "type": "String", "description": "Deadline if mentioned" }
          }
        }
      },
      "decisions_made": {
        "type": "Array",
        "description": "Key decisions made during the meeting",
        "items": { "type": "String", "description": "A decision" }
      }
    },
    "what_to_extract": "Extract action items and deadlines from this meeting",
    "include_usage": true
  }'

Response Example

{
  "status": "success",
  "data": {
    "action_items": [
      {
        "task": "Update the product roadmap with Q2 priorities",
        "assignee": "Sarah",
        "deadline": "Friday"
      },
      {
        "task": "Schedule customer interviews for user research",
        "assignee": "Mike",
        "deadline": "next week"
      }
    ],
    "decisions_made": [
      "Proceed with option B for the pricing model",
      "Delay the mobile app launch to Q3"
    ]
  },
  "file_info": {
    "id": "file_abc123",
    "name": "weekly-product-meeting.mp4",
    "size": 248517632,
    "type": "video/mp4",
    "duration": 3720.0,
    "status": "completed",
    "created_at": "2026-04-10T09:30:00Z",
    "updated_at": "2026-04-10T09:36:12Z",
    "has_transcript": true,
    "namespace_ids": ["ns_team_notes"],
    "namespaces": [
      {
        "id": "ns_team_notes",
        "name": "Team Notes"
      }
    ]
  },
  "usage": {
    "prompt_tokens": 3200,
    "completion_tokens": 120,
    "total_tokens": 3320
  }
}

The usage field is only included when include_usage=true in the request. file_info is included in the response metadata.

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
There is no speech-to-text billing on this endpoint
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)

API reference

Authorization

ApiKeyAuth

headerX-API-Key<token>

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

Request Body

body

file_id*string

ID of the uploaded file to extract data from

schema*

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

what_to_extract?string

Optional guidance for what to extract from the transcript

include_usage?boolean

When true, includes token usage statistics in the response

Defaultfalse

Response Body

Data extracted successfully

application/json

response

status?"success"

Value in"success"

data?

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

video_info?

Video metadata (title, channel, duration, views, etc.). Only present for /extract/video requests.

file_info?

File metadata (name, size, type, duration, etc.). Only present for /extract/file requests.

usage?

Per-call usage, only present when include_usage=true: the charges (charges, total_credits, credits_remaining_after, waived) and the token counts (prompt_tokens, completion_tokens, total_tokens) in one object.

Example Request

curl -X POST 'https://api.vidnavigator.com/v1/extract/file' \
  -H 'Content-Type: application/json' \
  -d '{
  "file_id": "string",
  "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"
    }
  }
}'

Example Request

curl -X POST 'https://api.vidnavigator.com/v1/extract/file' \  -H 'Content-Type: application/json' \  -d '{  "file_id": "string",  "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"    }  }}'

Example ResponseSchema

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

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

OverviewCopy Anchor Link

How It WorksCopy Anchor Link

Schema RulesCopy Anchor Link

Example UsageCopy Anchor Link

Response ExampleCopy Anchor Link

BillingCopy Anchor Link

API referenceCopy Anchor Link

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

On this page