Analyze the Scenes of a File
Start the scene analysis of a file already uploaded: what its picture shows, scene by scene, with the text readable on screen, as POST /watch does for an online video.
The scenes of a file are analyzed once and kept with it. Follow file_info.scenes_status on GET /file/{file_id}: it goes from processing to completed (the scenes are then in data.scenes) or failed (see file_info.scenes_error). POST /analyze/file and POST /extract/file read them when called with include_scenes=true.
Calling it again while the analysis runs, or once it is done, starts nothing new. After a failure it starts the analysis again. A new upload can ask for its scenes directly, with include_scenes on POST /upload/file.
No request body.
Start the scene analysis of a file already uploaded: what its picture shows, scene by scene, with the text readable on screen, as POST /watch does for an online video.
Overview
The scenes of a file are analyzed once and kept with it. This endpoint starts the analysis and answers at once; follow it on GET /file/{file_id}:
file_info.scenes_statusgoes fromprocessingtocompletedorfailed.- Once
completed, the scenes are returned indata.scenes, andPOST /analyze/fileandPOST /extract/fileuse them withinclude_scenes: true. - When
failed,file_info.scenes_errorsays why.
A new upload can ask for its scenes directly, with include_scenes=true on POST /upload/file.
Calling it again while the analysis runs, or once it is done, starts nothing new. After a failure it starts the analysis again.
Billing
The frames of a file are charged once, when its scenes are analyzed: 1 credit per 1,000 frames analyzed, with at least 334 frames per hour of video (frame_analysis). Reading the scenes afterwards, or using them in an analysis or an extraction, adds no frame charge. Nothing is charged for a file that has no picture.
Path Parameter
file_id(string, required) – The ID of the uploaded file. There is no request body.
Example Request
curl -X POST "https://api.vidnavigator.com/v1/file/file_abc123/scenes" \
-H "X-API-Key: YOUR_API_KEY"Responses
Started, or already running (202)
{
"status": "success",
"data": {
"file_id": "file_abc123",
"scenes_status": "processing",
"message": "Scene analysis started."
}
}Already available (200)
{
"status": "success",
"data": {
"file_id": "file_abc123",
"scenes_status": "completed",
"message": "The scenes of this file are already available."
}
}A file with no picture (400)
An audio file has nothing to show:
{
"status": "error",
"error": "frames_not_available",
"error_code": "frames_not_available",
"message": "This file has no picture we can read (an audio file, or a video without a video track)."
}Then
# Follow the analysis
curl "https://api.vidnavigator.com/v1/file/file_abc123" -H "X-API-Key: YOUR_API_KEY"
# Once scenes_status is "completed", use the scenes
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": "What is written on the label?", "include_scenes": true }'API reference
ApiKeyAuthX-API-Key<token>API key authentication. Include your VidNavigator API key in the X-API-Key header.
file_id*stringThe ID of the file to analyze
The scenes of this file are already available: nothing was started.
application/json- response
status?"success""success"data?curl -X POST 'https://api.vidnavigator.com/v1/file/string/scenes'{ "status": "success", "data": { "file_id": "string", "scenes_status": "processing", "message": "string" }}