---
title: "Request Description"
method: POST
path: "/video/description/{source_file_id}"
tags: ["accepts-api-key"]
---

# Request Description

`POST /video/description/{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/description/{source_file_id}`
- Auth: none declared

Run the description (Gemini analysis) task on an asset, or on a folder.

Requires WRITE access on the asset or admin.

For a single asset, ``needs_downscale`` reports whether a player/Gemini-
compatible video rendition is missing. When it is, we encode a compatible
proxy first and chain the description task after it (the downscale's
``link`` callback), so Gemini only runs once a usable rendition exists. The
returned ``task_id`` always tracks the description task, so callers poll the
same id in both cases.

Pointed at a folder, it queues a walk of that folder instead and returns as
soon as the walk is queued: ``task_id`` then tracks the fan-out, which
dispatches one description task per asset — each exactly as it would be
dispatched on its own, proxy encode included — and ``needs_downscale`` is
false, since which assets need one is only known once the walk runs. The
folder is walked recursively; assets the caller cannot write, and assets
whose media is not uploaded, are skipped. There is no limit on its size, and
every dispatched asset is billed — the preflight route reports how many that
will be before you commit to it.

An optional body forces the configuration to analyse under, so a one-off run
does not need a tellers-config committed to the folder tree first. It
replaces what the tree resolves rather than merging over it. Every entity id
in it is checked against the caller before anything is dispatched, and the
whole request is refused if one is not theirs. The same body on the preflight
route shows the resulting config first.

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

- GenerateDescriptionResponse
  - `task_id` string, required
  - `needs_downscale` boolean, required

## Other responses

- `422`: Validation Error

## Changes

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

[Operation history](https://skmtc.dev/tellers/apis/tellers-api/changes/video/description/: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)