Skip to Content

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.

POST
/file/{file_id}/scenes

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_status goes from processing to completed or failed.
  • Once completed, the scenes are returned in data.scenes, and POST /analyze/file and POST /extract/file use them with include_scenes: true.
  • When failed, file_info.scenes_error says 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
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

cURL
# 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

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Path Parameters

file_id*string

The ID of the file to analyze

Response Body

The scenes of this file are already available: nothing was started.

application/json
  1. response
status?"success"
Value in"success"
data?
Example Request
curl -X POST 'https://api.vidnavigator.com/v1/file/string/scenes'
Example Response
{  "status": "success",  "data": {    "file_id": "string",    "scenes_status": "processing",    "message": "string"  }}

On this page