> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://docs.vidnavigator.com/api-reference/endpoint/watch.md) 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}`](https://docs.vidnavigator.com/api-reference/endpoint/file-info.md):

- `file_info.scenes_status` goes from `processing` to `completed` or `failed`.
- Once `completed`, the scenes are returned in `data.scenes`, and [`POST /analyze/file`](https://docs.vidnavigator.com/api-reference/endpoint/analyze-file.md) and [`POST /extract/file`](https://docs.vidnavigator.com/api-reference/endpoint/extract-file.md) 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`](https://docs.vidnavigator.com/api-reference/endpoint/upload-file.md).

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

```bash 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)

```json
{
  "status": "success",
  "data": {
    "file_id": "file_abc123",
    "scenes_status": "processing",
    "message": "Scene analysis started."
  }
}
```

### Already available (200)

```json
{
  "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:

```json
{
  "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

```bash 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 }'
```

## OpenAPI

````yaml POST /file/{file_id}/scenes
openapi: 3.0.3
info:
  title: VidNavigator Developer API
  version: 1.0.0
servers:
  - url: https://api.vidnavigator.com/v1
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /file/{file_id}/scenes:
    post:
      summary: Analyze the scenes of an uploaded file
      description: |-
        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.
      operationId: analyzeFileScenes
      tags:
        - Files
      parameters:
        - name: file_id
          in: path
          required: true
          description: The ID of the file to analyze
          schema:
            type: string
      responses:
        "200":
          description: "The scenes of this file are already available: nothing was started."
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    properties:
                      file_id:
                        type: string
                      scenes_status:
                        type: string
                        enum:
                          - processing
                          - completed
                      message:
                        type: string
        "202":
          description: The scene analysis was started, or is already running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  data:
                    type: object
                    properties:
                      file_id:
                        type: string
                      scenes_status:
                        type: string
                        enum:
                          - processing
                          - completed
                      message:
                        type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "403":
          $ref: "#/components/responses/AccessDenied"
        "404":
          $ref: "#/components/responses/FileNotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          description: "`watch_unavailable`: scene analysis is temporarily unavailable."
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  error:
                    type: string
                    enum:
                      - watch_unavailable
                  message:
                    type: string
components:
  responses:
    BadRequest:
      description: Bad request - invalid parameters. On /transcribe the `error` field may be `missing_parameter`, `unsupported_platform`, `unsupported_url`, `invalid_url`, `request_body_required`, `video_too_long`, or `no_videos_found` (the post carries no video).
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
              message:
                type: string
    AccessDenied:
      description: Access denied - insufficient permissions
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - access_denied
              message:
                type: string
    FileNotFound:
      description: File not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - file_not_found
              message:
                type: string
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: string
                enum:
                  - metadata_fetch_failed
                  - audio_extraction_failed
                  - transcription_failed
                  - internal_server_error
              message:
                type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Include your VidNavigator API key in the X-API-Key header.
````
