Analyze uploaded file

curl --request POST \
  --url https://api.vidnavigator.com/v1/analyze/file \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "file_id": "<string>",
  "query": "What is discussed in this file?",
  "transcript_text": false,
  "include_usage": false
}
'

import requests

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

payload = {
    "file_id": "<string>",
    "query": "What is discussed in this file?",
    "transcript_text": False,
    "include_usage": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_id: '<string>',
    query: 'What is discussed in this file?',
    transcript_text: false,
    include_usage: false
  })
};

fetch('https://api.vidnavigator.com/v1/analyze/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/analyze/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 => json_encode([
    'file_id' => '<string>',
    'query' => 'What is discussed in this file?',
    'transcript_text' => false,
    'include_usage' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/analyze/file"

	payload := strings.NewReader("{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	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/analyze/file")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/analyze/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["Content-Type"] = 'application/json'
request.body = "{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}"

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

{
  "status": "success",
  "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>"
        }
      ]
    },
    "transcript": [
      {
        "text": "<string>",
        "start": 123,
        "end": 123
      }
    ],
    "transcript_analysis": {
      "summary": "<string>",
      "people": [
        {
          "name": "<string>",
          "context": "<string>"
        }
      ],
      "places": [
        {
          "name": "<string>",
          "context": "<string>"
        }
      ],
      "key_subjects": [
        {
          "name": "<string>",
          "description": "<string>",
          "importance": "<string>"
        }
      ],
      "timestamp": 123,
      "relevant_text": "<string>",
      "query_answer": {
        "answer": "<string>",
        "best_segment_index": 123,
        "relevant_segments": [
          "<string>"
        ]
      }
    }
  },
  "usage": {
    "charges": [
      {
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

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

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

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

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

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

Local Files

Analyze Uploaded File

Analyze an uploaded file and return comprehensive analysis results with intelligent caching.

Behavior:

If no query provided: Returns summary analysis (cached if available)
If query provided: Returns both summary (from cache if available) and fresh question analysis

Billing: analysis_request is token-based — quantity = ceil(total_tokens / 15000). One unit is charged up front as a credit gate; additional units are topped up at the end if the LLM call exceeded 15,000 tokens. The file’s transcript is read locally from your storage — no proxy fetch is involved. Set include_usage=true to receive the per-charge breakdown.

Optional: set transcript_text=true to return the transcript as a single text string instead of an array of segments.

POST

analyze

file

Analyze uploaded file

curl --request POST \
  --url https://api.vidnavigator.com/v1/analyze/file \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "file_id": "<string>",
  "query": "What is discussed in this file?",
  "transcript_text": false,
  "include_usage": false
}
'

import requests

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

payload = {
    "file_id": "<string>",
    "query": "What is discussed in this file?",
    "transcript_text": False,
    "include_usage": False
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_id: '<string>',
    query: 'What is discussed in this file?',
    transcript_text: false,
    include_usage: false
  })
};

fetch('https://api.vidnavigator.com/v1/analyze/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/analyze/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 => json_encode([
    'file_id' => '<string>',
    'query' => 'What is discussed in this file?',
    'transcript_text' => false,
    'include_usage' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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/analyze/file"

	payload := strings.NewReader("{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	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/analyze/file")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vidnavigator.com/v1/analyze/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["Content-Type"] = 'application/json'
request.body = "{\n  \"file_id\": \"<string>\",\n  \"query\": \"What is discussed in this file?\",\n  \"transcript_text\": false,\n  \"include_usage\": false\n}"

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

{
  "status": "success",
  "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>"
        }
      ]
    },
    "transcript": [
      {
        "text": "<string>",
        "start": 123,
        "end": 123
      }
    ],
    "transcript_analysis": {
      "summary": "<string>",
      "people": [
        {
          "name": "<string>",
          "context": "<string>"
        }
      ],
      "places": [
        {
          "name": "<string>",
          "context": "<string>"
        }
      ],
      "key_subjects": [
        {
          "name": "<string>",
          "description": "<string>",
          "importance": "<string>"
        }
      ],
      "timestamp": 123,
      "relevant_text": "<string>",
      "query_answer": {
        "answer": "<string>",
        "best_segment_index": 123,
        "relevant_segments": [
          "<string>"
        ]
      }
    }
  },
  "usage": {
    "charges": [
      {
        "quantity": 123,
        "credits": 123,
        "waived": true,
        "credits_saved": 123,
        "tokens": {
          "prompt_tokens": 123,
          "completion_tokens": 123,
          "total_tokens": 123
        }
      }
    ],
    "total_credits": 123,
    "waived": {
      "credits_saved": 123
    }
  }
}

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

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

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

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

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

Run AI-powered analysis on a previously uploaded audio/video file.

Overview

Similar to Analyze Video, but operates on files in your library.

Request Body

file_id (string, required): ID of the uploaded file to analyze
query (string, optional): Ask a specific question about the content

Billing

File analysis consumes analysis_request units based on context size. One unit covers up to 15,000 total tokens, and longer contexts are billed with ceil(total_tokens / 15000). For example, an analysis that uses 17,000 total tokens consumes 2 analysis_request units. One unit is charged up front as a credit gate; additional units are topped up at the end if the LLM call exceeded 15,000 tokens. The file’s transcript is read locally from your storage — no proxy fetch is involved, so no standard_request / residential_request is charged. Set include_usage: true to receive a usage block with the per-charge breakdown.

Example Request

cURL

curl -X POST "https://api.vidnavigator.com/v1/analyze/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "file_abc123",
    "query": "Summarize the key points"
  }'

Authorizations

X-API-Key

string

header

required

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

Body

application/json

file_id

string

required

ID of the uploaded file to analyze

query

string

Optional question about the file content

Example:

"What is discussed in this file?"

transcript_text

boolean

default:false

When true, returns the transcript as a single plain-text string instead of an array of segments.

include_usage

boolean

default:false

When true, the response includes a usage block listing every meter charged during this request, the total credits deducted, and the user's remaining balance.

Response

File analyzed successfully

status

enum<string>

Available options:

success

data

object

Show child attributes

usage

object

Per-call usage disclosure. Returned only when the caller passes include_usage=true in the request body. Lists every meter that fired during this request and the credits actually deducted. Multiple charges of the same meter inside one request are consolidated into a single entry (their quantities and credits are summed). When a charge was waived through a cache-hit sponsorship (e.g. NGO), it carries waived: true + credits_saved, and a top-level waived.credits_saved summary appears.

For endpoints that involve LLM analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the consolidated analysis_request charge entry carries a nested tokens object reporting the LLM input/output token tally for the request.

Show child attributes

API Documentation

Online media

Local Files

System

Analyze Uploaded File

Overview

Request Body

Billing

Example Request

Authorizations

Body

Response

​Overview

​Request Body

​Billing

​Example Request

Authorizations

Body

Response

Overview

Request Body

Billing

Example Request