Uploading and Processing Files

Overview

In addition to online videos, VidNavigator allows you to upload and process your own local audio and video files. This is useful for analyzing private content or files that are not publicly available on the web. Supported formats: mp4, webm, mov, avi, wmv, flv, mkv, m4a, mp3, mpeg, mpga, wav.

Prerequisites

A valid VidNavigator API key.
The Python or JavaScript SDK, version 2.1.0 (pip install vidnavigator==2.1.0 or npm install vidnavigator@2.1.0).

Organizing Files with Namespaces

You can organize your uploaded files into namespaces (like folders). When uploading, pass namespace_ids to assign the file to one or more namespaces. You can also manage namespaces later via the namespace endpoints. All file responses (list, info, search) include namespace_ids and namespaces fields showing which namespaces each file belongs to.

Billing

Uploading and processing audio/video files consumes transcription_hour usage for speech-to-text. 1 credit covers 3 hours of video/audio transcription. Uploaded files also count toward your plan’s storage quota.

Uploading a File

The upload is asynchronous by default: the API returns a file ID immediately and processes the file in the background. Pass wait_for_completion to block until processing has finished instead.

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()  # reads VIDNAVIGATOR_API_KEY

try:
    response = client.upload_file(
        "path/to/your/video.mp4",
        wait_for_completion=True,       # omit to return immediately
        namespace_ids=["ns_meetings"],  # optional
    )
    print(f"File ID: {response['file_id']}, status: {response['file_status']}")
except FileNotFoundError:
    print("Error: The file was not found at the specified path.")
except VidNavigatorError as e:
    print(f"An error occurred: {e}")

import { VidNavigatorClient, VidNavigatorError } from 'vidnavigator';

const vn = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY,
});

try {
  const upload = await vn.uploadFile({
    filePath: 'path/to/your/video.mp4',
    wait_for_completion: true,       // omit to return immediately
    namespace_ids: ['ns_meetings'],  // optional
  });
  console.log(`File ID: ${upload.file_id}, status: ${upload.file_status}`);
} catch (error) {
  if (error instanceof VidNavigatorError) {
    console.error(`An error occurred: ${error.message}`);
  } else {
    throw error; // e.g. ENOENT when the file does not exist
  }
}

Checking Processing Status

Without wait_for_completion, poll the file until its status is no longer processing, then read its transcript:

import time

file_id = client.upload_file("path/to/your/interview.mp3")["file_id"]

info = client.get_file(file_id).data.file_info
while info.status == "processing":
    time.sleep(5)
    info = client.get_file(file_id).data.file_info

if info.status == "failed":
    client.retry_file_processing(file_id)
else:
    resp = client.get_file(file_id, transcript_text=True)
    print(resp.data.transcript)

const { file_id } = await vn.uploadFile({ filePath: 'path/to/your/interview.mp3' });

let { file_info } = await vn.getFile(file_id);
while (file_info.status === 'processing') {
  await new Promise((r) => setTimeout(r, 5000));
  ({ file_info } = await vn.getFile(file_id));
}

if (file_info.status === 'failed') {
  await vn.retryFileProcessing(file_id);
} else {
  const { transcript } = await vn.getFile(file_id, { transcript_text: true });
  console.log(transcript);
}

Working with the File

Once processed, a file works just like an online video:

# Ask questions about it
analysis = client.analyze_file(file_id=file_id, query="What action items were discussed?")
print(analysis.data.transcript_analysis.query_answer.answer)

# Extract structured data
extraction = client.extract_file_data(
    file_id=file_id,
    schema={"action_items": {"type": "Array", "description": "Action items", "items": {"type": "String", "description": "One action item"}}},
)
print(extraction.data)

# Manage it
client.get_file_url(file_id)   # signed URL to view or download the file
client.get_files(limit=20, status="completed")
client.delete_file(file_id)

// Ask questions about it
const { transcript_analysis } = await vn.analyzeFile({ file_id, query: 'What action items were discussed?' });
console.log(transcript_analysis.query_answer?.answer);

// Extract structured data
const { data } = await vn.extractFileData({
  file_id,
  schema: { action_items: { type: 'Array', description: 'Action items', items: { type: 'String', description: 'One action item' } } },
});
console.log(data);

// Manage it
const { file_url } = await vn.getFileUrl(file_id); // signed URL to view or download the file
const { files } = await vn.getFiles({ limit: 20, status: 'completed' });
await vn.deleteFile(file_id);

Next Steps

Search the content of your uploaded files.
Organize files into namespaces with the SDK, or via the namespace endpoints.
Extract structured data from the transcript using a custom schema.
See the Upload File and File Info API references.

Get Started

User Guides

Uploading and Processing Files

Overview

Prerequisites

Organizing Files with Namespaces

Billing

Uploading a File

Checking Processing Status

Working with the File

Next Steps

​Overview

​Prerequisites

​Organizing Files with Namespaces

​Billing

​Uploading a File

​Checking Processing Status

​Working with the File

​Next Steps

Overview

Prerequisites

Organizing Files with Namespaces

Billing

Uploading a File

Checking Processing Status

Working with the File

Next Steps