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.
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 analyzequery(string, optional): Ask a specific question about the contentinclude_scenes(boolean, optional, defaultfalse): 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 answers409scenes_not_available, andscenes_statussays 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 -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
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
application/json- body
file_id*stringID of the uploaded file to analyze
query?stringOptional question about the file content
include_scenes?booleanWhen 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.
falsetranscript_text?booleanWhen true, returns the transcript as a single plain-text string instead of an array of segments.
falseinclude_usage?booleanWhen true, the response includes the usage block of this request.
falseFile analyzed successfully
application/json- response
status?"success""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.
curl -X POST 'https://api.vidnavigator.com/v1/analyze/file' \ -H 'Content-Type: application/json' \ -d '{ "file_id": "string"}'{ "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 } }}