Upload File
Upload a new audio or video file for analysis and start processing.
Supported formats:
- Video: mp4, webm, mov, avi, wmv, flv, mkv
- Audio: m4a, mp3, mpeg, mpga, wav
Processing options:
wait_for_completion=false(default): Returns immediately, processing happens in backgroundwait_for_completion=true: Waits for complete processing before returning response
Scenes: set include_scenes=true to also analyze the picture of a video file (what it shows, with the text readable on screen), next to its transcription. Follow file_info.scenes_status on GET /file/{file_id}; the scenes are returned there once it is completed. An audio file has no picture: its scenes_status ends as failed with frames_not_available. For a file already uploaded, use POST /file/{file_id}/scenes.
Size: files up to 500 MB. A larger file is refused with 413.
Upload audio or video files for transcription and analysis.
Overview
Upload your own audio or video files to VidNavigator for processing. The API supports a wide range of formats and provides flexible processing options.
Supported Formats
Video Formats
mp4, webm, mov, avi, wmv, flv, mkv
Audio Formats
m4a, mp3, mpeg, mpga, wav
Processing Options
- Asynchronous (default): Returns immediately, processing happens in background
- Synchronous: Waits for complete processing before returning response
- With the scenes (
include_scenes=true, video files): what the file shows is analyzed as well, once, and kept with it. Followfile_info.scenes_statusonGET /file/{file_id}. Charged per frame: 1 credit per 2,000 frames analyzed, with at least 667 frames per hour of video. An audio file has no picture: itsscenes_statusends asfailedwithframes_not_available, and nothing is charged for it.
Billing
File processing consumes transcription_hour usage for speech-to-text. 1 credit covers 3 hours of video/audio transcription. Uploaded files also count toward your storage quota.
Namespace Assignment
You can assign the uploaded file to one or more namespaces by including namespace_ids in the form data. This accepts a comma-separated string or a JSON array (e.g., '["ns1","ns2"]'). See Namespaces for managing namespaces.
Example Usage
curl -X POST "https://api.vidnavigator.com/v1/upload/file" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/your/video.mp4" \
-F "wait_for_completion=false"Response Examples
All response variants include data.file_info with namespace_ids and namespaces reflecting the file's namespace assignments.
When wait_for_completion is false (the default), the API responds immediately with a file ID and a processing status.
{
"status": "success",
"file_id": "file_abc123",
"file_name": "video.mp4",
"file_status": "processing",
"message": "File uploaded successfully and is being processed",
"data": {
"file_info": {
"id": "file_abc123",
"name": "video.mp4",
"size": 15728640,
"type": "video/mp4",
"status": "processing",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"has_transcript": false,
"namespace_ids": ["64a1b2c3d4e5f6789abc0001"],
"namespaces": [
{ "id": "64a1b2c3d4e5f6789abc0001", "name": "default" }
]
}
}
}When wait_for_completion is true, the API waits until processing is finished before responding.
{
"status": "success",
"file_id": "file_abc123",
"file_name": "video.mp4",
"file_status": "completed",
"message": "File processed successfully",
"data": {
"file_info": {
"id": "file_abc123",
"name": "video.mp4",
"size": 15728640,
"type": "video/mp4",
"duration": 330,
"status": "completed",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"has_transcript": true,
"namespace_ids": ["64a1b2c3d4e5f6789abc0001", "64a1b2c3d4e5f6789abc0002"],
"namespaces": [
{ "id": "64a1b2c3d4e5f6789abc0001", "name": "default" },
{ "id": "64a1b2c3d4e5f6789abc0002", "name": "Client Calls" }
]
},
"transcript": [
{
"text": "Welcome to this tutorial...",
"start": 0.0,
"end": 3.5
}
]
}
}When wait_for_completion is true and processing exceeds 15 minutes, the API returns a 202 Accepted response. Processing continues in the background — poll GET /file/{file_id} to check completion.
{
"status": "accepted",
"file_id": "file_abc123",
"file_name": "video.mp4",
"file_status": "processing",
"message": "File uploaded but processing is still in progress",
"note": "Processing is taking longer than expected. Use GET /file/{file_id} to check status.",
"data": {
"file_info": {
"id": "file_abc123",
"name": "video.mp4",
"size": 15728640,
"type": "video/mp4",
"status": "processing",
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"has_transcript": false,
"namespace_ids": ["64a1b2c3d4e5f6789abc0001"],
"namespaces": [
{ "id": "64a1b2c3d4e5f6789abc0001", "name": "default" }
]
}
}
}API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
multipart/form-data- body
file*unknownThe audio or video file to upload
wait_for_completion?stringIf 'true', waits until processing is complete before returning response
"false""true""false""1""0""yes""no""y""n"namespace_ids?stringOptional namespace IDs to assign the file to. Accepts a comma-separated string or a JSON array (e.g., '["ns1","ns2"]').
include_scenes?stringIf 'true', the scenes of the file (what its picture shows) are analyzed as well. Video files only.
"false""true""false"File uploaded successfully
application/json- response
status?"success""success"file_id?stringfile_name?stringfile_status?string"processing""completed"message?stringdata?curl -X POST 'https://api.vidnavigator.com/v1/upload/file' \ -F 'file=null'{ "status": "success", "file_id": "string", "file_name": "string", "file_status": "processing", "message": "string", "data": { "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", "scenes_status": "none", "frames_analyzed": 0, "scenes_error": { "error": "frames_not_available", "message": "string" }, "namespace_ids": [ "string" ], "namespaces": [ { "id": "string", "name": "string" } ] } }}