find-scene API

API for searching and downloading movie/TV show scenes by dialog, time, or visual description.

Base URL

https://api.find-scene.com

All endpoints are POST with Content-Type: application/json, except GET /api/operation/{id}.

Authentication

Every API request requires a _token field in the JSON body.

{ "_token": "user-api-token", ...other fields }

How to get a token

Go to https://find-scene.com and sign in
Open https://find-scene.com/settings
Click "Generate new token" — the token is shown once, so copy it immediately
Include it as _token in every API request body

To revoke a token, go to https://find-scene.com/settings and click "Revoke" next to the token you want to disable.

Response Format

All successful responses are wrapped in { "result": <structured object> }. Each endpoint returns a typed JSON object (not a plain string). Error responses use { "error": "message" } at the top level (HTTP 4xx/5xx) or { "result": { "error": "message" } } for domain-level errors within a 200 response.

Video Source Hash

An internal find-scene ID for a video file, starting with the video- prefix (e.g., video-3b7da43b43). Obtained from get_best_video_source. This is NOT an IMDB ID or filename. Required for downloads, frame extraction, and high-accuracy text source lookups.

Text Source Hash

An internal find-scene ID for a subtitle/text file, starting with the text- prefix (e.g., text-eb354dfaa7). Obtained from get_text_source or get_high_accuracy_text_source. Required for phrase search and subtitle retrieval. NOT a filename or IMDB ID.

Async Operations

get_best_video_source, get_text_source, get_high_accuracy_text_source, download_by_time, extract_frame, stitch_videos, stitch_videos_side_by_side and transcribe_by_time return an operation ID (not a direct result). You must poll GET /api/operation/{id} until status is completed, then use the result fields from the response.

Statuses: in_progress, completed, failed, cancelled

Time Format

All time parameters use HH:MM:SS format, e.g. "00:01:30".

Typical Workflows

Workflow 1: Find and download a scene by quote

1. quote_to_movie        -> identify which movie contains the quote
2. get_best_video_source -> returns operation ID, poll until completed to get videoHash
3. get_text_source       -> returns operation ID, poll until completed to get textSource hash
4. search_phrase         -> find exact timestamp of the quote
5. download_by_time      -> schedule clip download (returns operation ID)
6. GET /api/operation/id -> poll until completed, get download URL

Workflow 2: Download a scene by time

1. get_best_video_source -> returns operation ID, poll until completed to get videoHash
2. download_by_time      -> schedule download with start/end times
3. GET /api/operation/id -> poll until completed

Workflow 3: Search by visual scene description

1. find_by_scene_description -> search by what happens visually
2. get_best_video_source     -> returns operation ID, poll until completed to get videoHash
3. download_by_time          -> download the scene
4. GET /api/operation/id     -> poll until completed

Workflow 4: Find which episode contains a quote (TV series)

1. find_episode_by_phrase -> find season/episode for a phrase
2. get_best_video_source  -> returns operation ID, poll until completed to get videoHash
3. get_text_source        -> returns operation ID, poll until completed to get textSource
4. search_phrase          -> get exact timestamp
5. download_by_time       -> download clip
6. GET /api/operation/id  -> poll until completed

Workflow 5: Extract a frame / screenshot

1. get_best_video_source -> get videoHash
2. extract_frame         -> schedule frame extraction (returns operation ID)
3. GET /api/operation/id -> poll until completed, get image URL

Tips

Always get the video source hash first before attempting downloads or text source lookups.
Use get_high_accuracy_text_source (with videoHash) over get_text_source when you have a video source, for better subtitle timing alignment.
All async tools return operation IDs. Never return these to the user as download links. Always poll until you get the actual result.
Keep clip durations reasonable (under 60 seconds) to avoid long processing times.
For TV series, use find_episode_by_phrase first to identify the episode before searching within it.
The find_by_scene_description endpoint requires the video to have been indexed. If it returns no results, use request_indexing_for_scene_description and try again later.
OpenAPI spec is available at https://api.find-scene.com/api/openapi.json for machine-readable schema details.

Error Handling

400: Invalid parameters (check required fields)
401: Invalid or missing _token
500: Internal server error (retry or report)

API Endpoints Reference

`POST /api/get_best_video_source`

Schedules a task to get the best video source for a given video. The result will be automatically delivered when complete. You will be notified when the operation finishes — do not poll or check status.