Uploading and Processing Files
Learn how to upload your own video and audio files for transcription and analysis.
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.0ornpm 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}")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)Scenes of a File
A transcript is what a file says. Its scenes are what it shows: for each one a description of the picture and the text readable on screen. The scenes of a video file are analyzed once and kept with the file. Ask for them at upload, or later for a file that is already there. It needs version 2.5.0 of the SDKs.
import time
result = client.upload_file("./recipe.mp4", include_scenes=True) # at upload
file_id = result["file_id"]
# or, for an existing file:
client.analyze_file_scenes(file_id)
while True:
resp = client.get_file(file_id)
info = resp.data.file_info
if info.status == "completed" and info.scenes_status in ("completed", "failed"):
break
time.sleep(3)
for scene in resp.data.scenes or []:
print(f"[{scene.start:.0f}s] {scene.description} | on screen: {scene.on_screen_text}")file_info.scenes_status is none (never asked for), processing, completed or failed. An audio file has no picture: its scenes fail with frames_not_available, and nothing is charged for them.
Once the scenes are there, analysis and extraction of the file use them with include_scenes. Asked on a file that has none, they answer 409 scenes_not_available (ScenesNotAvailableError in the SDKs), and scenes_status says whether to start the analysis or to wait for it.
The frames of a file are charged once, when its scenes are analyzed: 1 credit per 2,000 frames analyzed, with at least 667 frames per hour of video. Using the scenes afterwards adds no frame charge.
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={
"type": "object",
"properties": {
"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)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 JSON Schema, or
what_to_extractin plain words. - See the Upload File and File Info API references.