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

Content-Type: application/json

GET /api/operation/{id}

Authentication

Every API request requires a

_token

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

How to get a token

1. Go to https://find-scene.com and sign in
2. Open https://find-scene.com/settings
3. Click "Generate new token" — the token is shown once, so copy it immediately
4. 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> }

{ "error": "message" }

{ "result": { "error": "message" } }

Video Source Hash

An internal find-scene ID for a video file. Obtained from

get_best_video_source

Text Source Hash

An internal find-scene ID for a subtitle/text file. Obtained from

get_text_source

get_high_accuracy_text_source

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

transcribe_by_time

GET /api/operation/{id}

completed

Statuses:

in_progress

completed

failed

cancelled

Video Query Object

Many endpoints accept a video query object with these optional fields:

movieOrTVShowName

dubbed

animated

blackAndWhite

year

isSeries

season

episode

Time Format

All time parameters use

HH:MM:SS

"00:01:30"

Display Params Object

Used by

download_by_time

extract_frame

removeWatermark

false

gif

false

mobile

false

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.

Request body (JSON, requires

_token

query

timeoutSeconds

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/compute_running_time

Compute the running time of a video.

Request body (JSON, requires

_token

imdbId

Response:

{ "runtimeSeconds": number | null }

POST /api/get_high_accuracy_text_source

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

Request body (JSON, requires

_token

language

query

videoHash

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/get_text_source

Schedules a task to get a text source for given video details. If you have the video source use the other version, it will be more accurate with the timings. Note that this outputs a text source hash. NOT a video source hash. The result will be automatically delivered when complete. You will be notified when the operation finishes — do not poll or check status.

Request body (JSON, requires

_token

language

query

minDuration

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/search_phrase

Search phrases in video text.

Request body (JSON, requires

_token

phraseSearchParams

textSource

Response:

{ "occurrences": object[] }

{ "error": string }

POST /api/get_srt_entries_around_phrase

Get subtitle entries (text and times) around a phrase, for a given video. Returns entries within a time window before and after the phrase.

Request body (JSON, requires

_token

limit

skip

textSource

phrase

secondsBefore

secondsAfter

Response:

{ "occurrences": object[] }

{ "error": string }

POST /api/get_srt_entries_by_time_range

Get subtitle entries (text and times) for a given video and time range.

Request body (JSON, requires

_token

videoQuery

startTime

endTime

subsLanguage

Response:

{ "srt": string }

{ "error": string }

POST /api/download_by_time

Schedules a task to download a video part by time. The result will be automatically delivered to the user (UI + email) and billed when complete. You will be notified when the operation finishes — do not poll or check status.

Request body (JSON, requires

_token

startTime

endTime

srtOffset

videoHash

textSource

displayParams

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/extract_frame

Extract a single frame from a video at a specific time. Useful for creating stickers or screenshots. The result will be automatically delivered to the user when complete. You will be notified when the operation finishes — do not poll or check status.

Request body (JSON, requires

_token

videoHash

time

textSource

overrideTextTop

overrideTextBottom

displayParams

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/stitch_videos

Stitch multiple previously downloaded video clips into a single video. Accepts URLs from completed download_by_time operations. The result will be automatically delivered to the user (UI + email) and billed when complete. You will be notified when the operation finishes — do not poll or check status.

Request body (JSON, requires

_token

urls

displayParams

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/stitch_videos_side_by_side

Place multiple previously downloaded video clips side by side in a single frame. All videos play simultaneously. Accepts URLs from completed download_by_time operations. The result will be automatically delivered to the user (UI + email) and billed when complete. You will be notified when the operation finishes — do not poll or check status.

Request body (JSON, requires

_token

urls

displayParams

Response:

{ "operationId": string }

{ "error": string }

This is an async endpoint. Returns

{ "result": { "operationId": "..." } }

GET /api/operation/{id}

POST /api/cancel_operation

Cancel a stuck async operation by its ID.

Request body (JSON, requires

_token

id

Response:

{ "cancelled": boolean, "operationId": string }

{ "cancelled": boolean, "reason": string }

POST /api/is_string_a_movie_name

Check if the string is a movie name

Request body (JSON, requires

_token

string

Response:

{ "isMovieName": boolean }

POST /api/quote_to_movie

Get movie name from quote

Request body (JSON, requires

_token

quote

Response:

{ "candidates": string[] }

POST /api/find_episode_by_phrase

Find a series episode by a phrase. This is not for movies, but tv shows.

Request body (JSON, requires

_token

phrase

videoQuery

season

limit

Response:

{ "episodes": object[] }

POST /api/query_imdb

Get movie information from IMDB, including the imdb id itself, if you only have the title.

Request body (JSON, requires

_token

title

year

imdbId

season

episode

Response:

{ "name": string, "imdb": string, "year": number, "season": number, "episode": number }

POST /api/popular_quotes_from_title

Get popular quotes from a movie or TV show title

Request body (JSON, requires

_token

limit

name

imdb

Response:

{ "quotes": string[] }

POST /api/find_by_scene_description

Search scene by non dialog description.

Request body (JSON, requires

_token

description

video

nResults

nSkip

scoreThreshold

Response:

{ "results": object[], "warning": string }

{ "error": string }

POST /api/request_indexing_for_scene_description

Request indexing of a video. If it's a series we need to know the season and episode.

Request body (JSON, requires

_token

video

Response:

{ "requested": boolean }

POST /api/check_quota

Check how many search credits the current user has remaining. Credits work on a rolling 30-day window — each credit returns exactly 30 days after it was used. If the user is low on credits, tell them when their next credit returns.

Response:

{ "creditsRemaining": number, "nextCreditReturnMs": number }

GET /api/operation/{id}

Poll the status of an async operation (returned by download_by_time or extract_frame)

Path parameters:

id

Response: object