Skip to Content

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

Set include_usage=true to receive the usage block, with the request's token counts.

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

Scenes: set include_scenes=true to analyze the file from its transcript and its scenes together. data then also holds scenes and frames_analyzed. The scenes are the ones kept with the file: they are analyzed beforehand, at the upload with include_scenes or with POST /file/{file_id}/scenes. A file that has none is answered 409 (scenes_not_available). A file without speech is analyzed from its scenes, with transcript_error.

POST
/analyze/file

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
  • include_scenes (boolean, optional, default false): Also use what the file shows — the scenes kept with the file, with the text on screen. The file must have its scenes: see Analyze the scenes of a file. Otherwise the call answers 409 scenes_not_available, and scenes_status says where their analysis stands. Using the scenes adds no frame charge: the frames of a file are charged once, when its scenes are analyzed.

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

API reference

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Request Body

application/json
  1. body
file_id*string

ID of the uploaded file to analyze

query?string

Optional question about the file content

include_scenes?boolean

When true, the scenes kept with the file (what it shows, with the text readable on screen) are used together with its transcript. The scenes of a file are analyzed beforehand: at its upload with include_scenes, or with POST /file/{file_id}/scenes.

Defaultfalse
transcript_text?boolean

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

Defaultfalse
include_usage?boolean

When true, the response includes the usage block of this request.

Defaultfalse

Response Body

File analyzed successfully

application/json
  1. response
status?"success"
Value in"success"
data?
usage?

Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.

For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.

Example Request
curl -X POST 'https://api.vidnavigator.com/v1/analyze/file' \  -H 'Content-Type: application/json' \  -d '{  "file_id": "string"}'
Example Response
{  "status": "success",  "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"        }      ]    },    "transcript": [      {        "text": "string",        "start": 0,        "end": 0      }    ],    "transcript_error": {      "error": "transcript_not_available",      "message": "string"    },    "transcript_analysis": {      "summary": "string",      "people": [        {          "name": "string",          "context": "string"        }      ],      "places": [        {          "name": "string",          "context": "string"        }      ],      "key_subjects": [        {          "name": "string",          "description": "string",          "importance": "string"        }      ],      "timestamp": 0,      "relevant_text": "string",      "query_answer": {        "answer": "string",        "best_segment_index": 0,        "relevant_segments": [          "string"        ]      }    },    "scenes": [      {        "start": 4,        "end": 12,        "description": "A presenter stands in front of a world map and points at Europe.",        "on_screen_text": "BREAKING NEWS"      }    ],    "frames_analyzed": 23  },  "usage": {    "charges": [      {        "service_type": "standard_request",        "quantity": 0,        "credits": 0,        "waived": true,        "credits_saved": 0,        "tokens": {          "prompt_tokens": 0,          "completion_tokens": 0,          "total_tokens": 0        }      }    ],    "total_credits": 0,    "waived": {      "credits_saved": 0    }  }}

On this page