---
title: "Analysis Preflight"
method: POST
path: "/video/analysis-preflight/{source_file_id}"
tags: ["accepts-api-key"]
---

# Analysis Preflight

`POST /video/analysis-preflight/{source_file_id}`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/video/analysis-preflight/{source_file_id}`
- Auth: none declared

Report what analysing this asset would do, without dispatching anything.

The dry run for the two routes above, and it takes what they take: a file or
a folder. ``description_asset_count`` and ``transcript_asset_count`` are how
many assets each would dispatch — 0 or 1 for a file, the whole subtree for a
folder — counted through the very same path, permission, type and
upload-status filters the walk uses, so the number is what will actually
run rather than an estimate.

``config`` is the tellers-config the dispatched tasks will read, resolved at
this asset's own path. It is a complete ``TellersConfigFile`` — the same
object ``GET /asset/tellers-config/{asset_id}`` returns — with the merged
analysis settings and entity ids in it rather than beside it, so reading
``config.analysis`` gives what will actually apply. ``config_assets`` lists
the config files that contributed, nearest last.

For a folder the counts cover the whole subtree while ``config`` is what a
file sitting directly in it resolves. ``overriding_config_assets`` lists the
tellers-configs nested deeper that make those two disagree: assets under one
of those resolve it instead, so while this is non-empty the reported config
does not describe everything counted. It is capped, and
``overriding_config_assets_truncated`` says when there were more.

An optional body forces a configuration, and ``config`` then reports what
that leaves in force — through ``apply_config_override``, the same function
the analysis itself applies it with, so what this shows is what would run.
Since an override replaces the folder tree outright, this is also how to see
what a given body drops: ``config_assets`` comes back empty, and any entity
the tree contributed is gone unless the body names it again. Its entity ids
are validated exactly as the run routes validate them, which makes this the
way to find out whether an override will be accepted without spending
anything on it.

It is a POST because of that body, not because it changes anything: it
dispatches nothing and bills nothing.

Requires WRITE access, like the routes it previews: a folder's counts only
include assets the caller can write, so the same call by two people can
legitimately return different numbers.

## Path parameters

- `source_file_id` string, uuid, required

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Request body

- AnalysisConfigOverrideRequest: A tellers-config supplied with the request instead of read from a folder.
  - `config` TellersConfigFile, required
    - `entity_to_use` string[]
    - `analysis` AssetAnalysisSettings
      - `reasoning` 'low' | 'medium' | 'high', nullable
      - `fps` number, nullable
      - `entity_quality` 'low' | 'medium' | 'high', nullable
      - `asset_quality` 'low' | 'medium' | 'high', nullable
      - `prompt` string, nullable
      - `long_video` LongVideoAnalysisSettings: How descriptions of long videos differ from short ones. Only scene-description generation reads this; ``video_analyse_gemini`` takes its processing mode as a tool argument instead. Every field is optional so a folder config can override one of them and inherit the rest.
        - `enabled` boolean, nullable: Whether videos longer than 'min_duration_s' use these settings. When false, every video is described like a short one (static frame sampling, 5-minute chunks).
        - `min_duration_s` integer, nullable: Videos longer than this many seconds count as long.
        - `processing` 'static' | 'agentic', nullable: 'agentic' lets Gemini pick which frames to look at (cheaper on long footage); 'static' samples at the configured fps.
        - `split_duration_s` integer, nullable: Length in seconds of each Gemini call a long video is split into. 0 sends the whole video in one call.
    - `generate_stt_from_op_atom` boolean
    - `generate_stt_from_master_clip` boolean
    - `generate_stt_with_diarization` boolean: Whether speech-to-text also splits the audio by speaker. On by default: it costs no more than a plain transcription, so the transcript carries a 'speakers' timeline naming who talks over each stretch of the media unless a config turns it off. The words themselves are unchanged either way.
    - `generate_description_from_op_atom` boolean
    - `generate_description_from_master_clip` boolean
    - `merge_strategy` 'merge' | 'override': How this config combines with the configs of its parent folders. 'merge' inherits them and overrides field by field; 'override' ignores them.
    - `merge_parent_config` boolean: Deprecated and ignored. Superseded by 'merge_strategy'; it was never settable, so it is always false.

## Response `200`

Successful Response

- AnalysisPreflightResponse
  - `asset_id` string, required
  - `in_app_path` string, required
  - `is_folder` boolean, required
  - `description_asset_count` integer, required
  - `transcript_asset_count` integer, required
  - `config` TellersConfigFile, required
    - `entity_to_use` string[]
    - `analysis` AssetAnalysisSettings
      - `reasoning` 'low' | 'medium' | 'high', nullable
      - `fps` number, nullable
      - `entity_quality` 'low' | 'medium' | 'high', nullable
      - `asset_quality` 'low' | 'medium' | 'high', nullable
      - `prompt` string, nullable
      - `long_video` LongVideoAnalysisSettings: How descriptions of long videos differ from short ones. Only scene-description generation reads this; ``video_analyse_gemini`` takes its processing mode as a tool argument instead. Every field is optional so a folder config can override one of them and inherit the rest.
        - `enabled` boolean, nullable: Whether videos longer than 'min_duration_s' use these settings. When false, every video is described like a short one (static frame sampling, 5-minute chunks).
        - `min_duration_s` integer, nullable: Videos longer than this many seconds count as long.
        - `processing` 'static' | 'agentic', nullable: 'agentic' lets Gemini pick which frames to look at (cheaper on long footage); 'static' samples at the configured fps.
        - `split_duration_s` integer, nullable: Length in seconds of each Gemini call a long video is split into. 0 sends the whole video in one call.
    - `generate_stt_from_op_atom` boolean
    - `generate_stt_from_master_clip` boolean
    - `generate_stt_with_diarization` boolean: Whether speech-to-text also splits the audio by speaker. On by default: it costs no more than a plain transcription, so the transcript carries a 'speakers' timeline naming who talks over each stretch of the media unless a config turns it off. The words themselves are unchanged either way.
    - `generate_description_from_op_atom` boolean
    - `generate_description_from_master_clip` boolean
    - `merge_strategy` 'merge' | 'override': How this config combines with the configs of its parent folders. 'merge' inherits them and overrides field by field; 'override' ignores them.
    - `merge_parent_config` boolean: Deprecated and ignored. Superseded by 'merge_strategy'; it was never settable, so it is always false.
  - `config_assets` AnalysisConfigAsset[], required
    - `asset_id` string, nullable, required
    - `in_app_path` string, nullable, required
  - `overriding_config_assets` AnalysisConfigAsset[], required
    - `asset_id` string, nullable, required
    - `in_app_path` string, nullable, required
  - `overriding_config_assets_truncated` boolean, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-05** `fdaa0fa44a26`: 2 info
  - added the new optional request property `anyOf[subschema #1: AnalysisConfigOverrideRequest]/config/analysis/anyOf[subschema #1: AssetAnalysisSettings]/long_video`
  - added the optional property `config/analysis/anyOf[subschema #1: AssetAnalysisSettings]/long_video` to the response with the `200` status

[Operation history](https://skmtc.dev/tellers/apis/tellers-api/changes/video/analysis-preflight/:source_file_id/post.md)

---

[API](https://skmtc.dev/tellers/apis/tellers-api.md) - [All operations](https://skmtc.dev/tellers/apis/tellers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tellers/apis/tellers-api/revisions/fdaa0fa44a26?raw)