Upload File

Upload a file for analysis

curl --request POST \
  --url https://api.vidnavigator.com/v1/upload/file \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form wait_for_completion=false \
  --form 'namespace_ids=<string>'

import requests

url = "https://api.vidnavigator.com/v1/upload/file"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "wait_for_completion": "false",
    "namespace_ids": "<string>"
}
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('wait_for_completion', 'false');
form.append('namespace_ids', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.vidnavigator.com/v1/upload/file', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vidnavigator.com/v1/upload/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidnavigator.com/v1/upload/file"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/upload/file")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/upload/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "file_id": "<string>",
  "file_name": "<string>",
  "message": "<string>",
  "data": {
    "file_info": {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "type": "<string>",
      "duration": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "original_file_date": "2023-11-07T05:31:56Z",
      "has_transcript": true,
      "error_message": "<string>",
      "namespace_ids": [
        "<string>"
      ],
      "namespaces": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  }
}

{
  "status": "accepted",
  "file_id": "<string>",
  "file_name": "<string>",
  "file_status": "processing",
  "message": "<string>",
  "note": "<string>",
  "data": {
    "file_info": {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "type": "<string>",
      "duration": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "original_file_date": "2023-11-07T05:31:56Z",
      "has_transcript": true,
      "error_message": "<string>",
      "namespace_ids": [
        "<string>"
      ],
      "namespaces": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  }
}

{
  "status": "error",
  "error": "<string>",
  "message": "<string>"
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "storage_quota_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "internal_server_error",
  "message": "<string>"
}

{
  "status": "error",
  "error": "storage_not_configured",
  "message": "<string>"
}

POST

upload

file

Upload a file for analysis

curl --request POST \
  --url https://api.vidnavigator.com/v1/upload/file \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file' \
  --form wait_for_completion=false \
  --form 'namespace_ids=<string>'

import requests

url = "https://api.vidnavigator.com/v1/upload/file"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "wait_for_completion": "false",
    "namespace_ids": "<string>"
}
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('wait_for_completion', 'false');
form.append('namespace_ids', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://api.vidnavigator.com/v1/upload/file', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vidnavigator.com/v1/upload/file",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Content-Type: multipart/form-data",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vidnavigator.com/v1/upload/file"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vidnavigator.com/v1/upload/file")
  .header("X-API-Key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/upload/file")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"wait_for_completion\"\r\n\r\nfalse\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"namespace_ids\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "file_id": "<string>",
  "file_name": "<string>",
  "message": "<string>",
  "data": {
    "file_info": {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "type": "<string>",
      "duration": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "original_file_date": "2023-11-07T05:31:56Z",
      "has_transcript": true,
      "error_message": "<string>",
      "namespace_ids": [
        "<string>"
      ],
      "namespaces": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  }
}

{
  "status": "accepted",
  "file_id": "<string>",
  "file_name": "<string>",
  "file_status": "processing",
  "message": "<string>",
  "note": "<string>",
  "data": {
    "file_info": {
      "id": "<string>",
      "name": "<string>",
      "size": 123,
      "type": "<string>",
      "duration": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "original_file_date": "2023-11-07T05:31:56Z",
      "has_transcript": true,
      "error_message": "<string>",
      "namespace_ids": [
        "<string>"
      ],
      "namespaces": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  }
}

{
  "status": "error",
  "error": "<string>",
  "message": "<string>"
}

{
  "status": "error",
  "error": "limit_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "storage_quota_exceeded",
  "message": "<string>"
}

{
  "status": "error",
  "error": "internal_server_error",
  "message": "<string>"
}

{
  "status": "error",
  "error": "storage_not_configured",
  "message": "<string>"
}

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

Billing

File processing consumes transcription_hour usage for speech-to-text. 1 credit covers 1 hour 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"

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=true"

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 "namespace_ids=64a1b2c3d4e5f6789abc0002"

import requests

url = "https://api.vidnavigator.com/v1/upload/file"
headers = {"X-API-Key": "YOUR_API_KEY"}

with open("video.mp4", "rb") as f:
    files = {"file": f}
    data = {"wait_for_completion": "false"}
    response = requests.post(url, headers=headers, files=files, data=data)

result = response.json()
print(f"File ID: {result['file_id']}")

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('wait_for_completion', 'false');

const response = await fetch('https://api.vidnavigator.com/v1/upload/file', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();

Response Examples

All response variants include data.file_info with namespace_ids and namespaces reflecting the file’s namespace assignments.

201 - Asynchronous Response

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

201 - Synchronous Response

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
      }
    ]
  }
}

202 - Processing Timeout

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

Authorizations

X-API-Key

string

header

required

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

Body

multipart/form-data

file

required

The audio or video file to upload

wait_for_completion

enum<string>

default:false

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

Available options:

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"]').

Response

File uploaded successfully

status

enum<string>

Available options:

success

file_id

string

file_name

string

file_status

enum<string>

Available options:

processing,

completed

message

string

data

object

Show child attributes

Get TikTok Search Result List Files

API Documentation

Online media

Local Files

System

Overview

Supported Formats

Video Formats

Audio Formats

Processing Options

Billing

Namespace Assignment

Example Usage

Response Examples

Authorizations

Body

Response

​Overview

​Supported Formats

Video Formats

Audio Formats

​Processing Options

​Billing

​Namespace Assignment

​Example Usage

​Response Examples

Authorizations

Body

Response

Overview

Supported Formats

Processing Options

Billing

Namespace Assignment

Example Usage

Response Examples