Skip to Content

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 background
  • wait_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.

POST
/upload/file

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. Follow file_info.scenes_status on GET /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: its scenes_status ends as failed with frames_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.

API reference

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Request Body

multipart/form-data
  1. body
file*unknown

The audio or video file to upload

wait_for_completion?string

If 'true', waits until processing is complete before returning response

Default"false"
Value in"true""false""1""0""yes""no""y""n"
namespace_ids?string

Optional namespace IDs to assign the file to. Accepts a comma-separated string or a JSON array (e.g., '["ns1","ns2"]').

include_scenes?string

If 'true', the scenes of the file (what its picture shows) are analyzed as well. Video files only.

Default"false"
Value in"true""false"

Response Body

File uploaded successfully

application/json
  1. response
status?"success"
Value in"success"
file_id?string
file_name?string
file_status?string
Value in"processing""completed"
message?string
data?
Example Request
curl -X POST 'https://api.vidnavigator.com/v1/upload/file' \  -F 'file=null'
Example Response
{  "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"        }      ]    }  }}

On this page