---

name: find-scene description: Search movie and TV show scenes by dialog, time, or visual description. Download video clips, extract frames, find quotes, identify movies from quotes, and query IMDB data. Use when the user wants to find a specific scene, download a clip, search for a quote in a movie/show, extract a frame, or get movie information via the find-scene API.

find-scene API Skill

Search and download movie/TV show scenes by dialog, time, or visual description.

Authentication

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

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

How to get a token

1. Go to https://find-scene.com and sign in
2. In the chat, ask the bot to "generate an API token"
3. The bot will return a token string — keep it secret
4. Include it as _token in every API request body

To revoke a token, ask the bot to "revoke my API token".

Base URL

https://api.find-scene.com

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

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

download_by_time and extract_frame return an operation ID (not a download URL). You must poll GET /api/operation/{id} until status is completed, then use the url field from the response.

Statuses: in_progress, completed, failed, cancelled

Video Query Object

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

| Field | Type | Description | |-------|------|-------------| | movieOrTVShowName | string/null | Movie or TV show name | | dubbed | string/null | Dubbing language code, e.g. "en", "de", "pt-br" | | animated | boolean/null | Is the video animated | | blackAndWhite | boolean/null | Is the video black and white | | year | number/null | Year (for distinguishing remakes) | | isSeries | boolean/null | User explicitly said it's a series | | season | number/null | Season number (series only) | | episode | number/null | Episode number (series only) |

Time Format

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

Display Params Object

Used by download_by_time and extract_frame:

| Field | Type | Default | Description | |-------|------|---------|-------------| | removeWatermark | boolean | false | Pro users only | | gif | boolean | false | Only if user explicitly asked for GIF | | mobile | boolean | false | Crop to mobile format. Only if user asked |

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 -> get videoHash for that movie
3. get_text_source       -> 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 -> 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     -> get videoHash for the match
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  -> get videoHash with season/episode
3. get_text_source        -> 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

API Endpoints Reference

Video Source Tools

POST /api/get_best_video_source

Get the best video source for a movie or TV show.

{
  "_token": "...",
  "query": {
    "movieOrTVShowName": "The Matrix",
    "year": 1999
  },
  "timeoutSeconds": 60
}

• query (required): Video query object (see above)
• timeoutSeconds (optional): Max wait time. Default 60. Do not manually convert minutes to seconds.
• Returns: { "result": { "sources": ["videoHash1", ...], "error": "..." } } — sources is always present; error is optional

Text Source Tools

POST /api/get_text_source

Get a text/subtitle source hash by movie details. Less accurate timing than get_high_accuracy_text_source.

{
  "_token": "...",
  "query": { "movieOrTVShowName": "The Matrix" },
  "language": "en",
  "minDuration": 3600
}

• query (required): Video query object
• language (optional): Subtitle language, e.g. "en", "pt-br", "de"
• minDuration (optional): Minimum subtitle file duration in seconds
• Returns: { "result": { "textSources": ["hash1", ...] } } or { "result": { "error": "..." } }

POST /api/get_high_accuracy_text_source

Get a text source with accurate timing. Requires a videoHash from get_best_video_source.

{
  "_token": "...",
  "query": { "movieOrTVShowName": "The Matrix" },
  "videoHash": "abc123...",
  "language": "en"
}

• query (required): Video query object
• videoHash (required): From get_best_video_source
• language (optional): Subtitle language
• Returns: { "result": { "textSources": ["hash1", ...] } } or { "result": { "error": "..." } }

Text Search Tools

POST /api/search_phrase

Search for a phrase/quote in a text source's subtitles.

{
  "_token": "...",
  "textSource": "textSourceHash",
  "phraseSearchParams": {
    "phraseStart": "I know kung fu",
    "phraseEnd": "",
    "nSkip": 0,
    "maxOccurrences": 1
  }
}

• textSource (required): Text source hash
• phraseSearchParams.phraseStart (required): The phrase to search. Do not include speaker names. For long text, split using phraseEnd.
• phraseSearchParams.phraseEnd (optional): End of phrase if split
• phraseSearchParams.nSkip (required): Results to skip (default 0)
• phraseSearchParams.maxOccurrences (required): Max results (default 1)
• Returns: { "result": { "occurrences": [{ "time": "HH:MM:SS", "rangeStart": "HH:MM:SS", "rangeEnd": "HH:MM:SS", "srt": "subtitle text" }, ...] } } or { "result": { "error": "..." } }

POST /api/get_srt_entries_around_phrase

Get subtitle entries in a time window around a phrase occurrence.

{
  "_token": "...",
  "textSource": "textSourceHash",
  "phrase": "I know kung fu",
  "limit": 1,
  "skip": 0,
  "secondsBefore": 5,
  "secondsAfter": 5
}

All fields are required.

• Returns: same as search_phrase — { "result": { "occurrences": [...] } } or { "result": { "error": "..." } }

POST /api/get_srt_entries_by_time_range

Get subtitle entries for a video within a time range.

{
  "_token": "...",
  "videoQuery": { "movieOrTVShowName": "The Matrix" },
  "startTime": "00:30:00",
  "endTime": "00:31:00",
  "subsLanguage": "en"
}

• videoQuery (required): Video query object
• startTime, endTime (required): Time range in HH:MM:SS
• subsLanguage (optional): Subtitle language
• Returns: { "result": { "srt": "subtitle text" } } or { "result": { "error": "..." } }

Video Download Tools

POST /api/download_by_time

Schedule a video clip download. Returns an operation ID, NOT a URL.

{
  "_token": "...",
  "videoHash": "abc123...",
  "startTime": "00:30:00",
  "endTime": "00:30:15",
  "textSource": "textSourceHash",
  "srtOffset": 0,
  "displayParams": {
    "removeWatermark": false,
    "gif": false,
    "mobile": false
  }
}

• videoHash (required): From get_best_video_source
• startTime, endTime (required): Clip bounds in HH:MM:SS
• displayParams (required): See display params object above
• textSource (optional): To burn subtitles into the clip
• srtOffset (optional): Subtitle time correction offset
• Returns: { "result": { "operationId": "..." } } or { "result": { "error": "..." } } — you MUST poll the operationId

POST /api/extract_frame

Extract a single frame/screenshot from a video. Returns an operation ID.

{
  "_token": "...",
  "videoHash": "abc123...",
  "time": "00:30:05",
  "textSource": "textSourceHash",
  "overrideTextTop": "TOP TEXT",
  "overrideTextBottom": "BOTTOM TEXT",
  "displayParams": {
    "removeWatermark": false,
    "gif": false,
    "mobile": false
  }
}

• videoHash (required): From get_best_video_source
• time (required): Frame time in HH:MM:SS
• textSource (optional): Overlay subtitles on frame
• overrideTextTop, overrideTextBottom (optional): Custom text overlay (meme mode)
• displayParams (optional): See display params object
• Returns: { "result": { "operationId": "..." } } or { "result": { "error": "..." } } — you MUST poll the operationId

POST /api/cancel_operation

Cancel a stuck async operation.

{ "_token": "...", "id": "operation-id" }

• Returns: { "result": { "cancelled": true, "operationId": "..." } } or { "result": { "cancelled": false, "reason": "..." } }

Async Operation Polling

GET /api/operation/{id}

Poll the status of an async operation. No request body. No auth token needed in query (it was provided when creating the operation).

Response:

{
  "status": "completed",
  "progress": 100,
  "result": "...",
  "url": "https://signed-download-url..."
}

Polling strategy: Wait 2-3 seconds between polls. Typical downloads complete in 10-30 seconds. Give up after ~2 minutes.

Movie Information Tools

POST /api/query_imdb

Get movie/show information from IMDB.

{
  "_token": "...",
  "title": "The Matrix",
  "year": 1999,
  "imdbId": "tt0133093",
  "season": 1,
  "episode": 1
}

• title (required): Movie/show title
• All other fields optional
• Returns: { "result": { "name": "...", "imdb": "tt...", "year": 1999, "season": 1, "episode": 1, ... } } — movie metadata object with available IMDB fields

POST /api/is_string_a_movie_name

Check if a string is a movie/show name.

{ "_token": "...", "string": "The Matrix" }

• Returns: { "result": { "isMovieName": true } } or { "result": { "isMovieName": false } }

POST /api/quote_to_movie

Identify which movie a quote is from.

{ "_token": "...", "quote": "I know kung fu" }

• Returns: { "result": { "candidates": ["Movie Name 1", "Movie Name 2", ...] } }

POST /api/popular_quotes_from_title

Get popular quotes from a movie or TV show.

{
  "_token": "...",
  "name": "The Matrix",
  "limit": 10,
  "imdb": "tt0133093"
}

• name (required): Movie/show name
• limit (required): Max number of quotes
• imdb (optional): IMDB ID
• Returns: { "result": { "quotes": ["quote 1", "quote 2", ...] } }

POST /api/compute_running_time

Get running time of a movie/show.

{ "_token": "...", "imdbId": "tt0133093" }

• Returns: { "result": { "runtimeSeconds": 8160 } } or { "result": { "runtimeSeconds": null } } if not found

TV Series Tools

POST /api/find_episode_by_phrase

Find which episode of a TV series contains a phrase.

{
  "_token": "...",
  "phrase": "We were on a break",
  "videoQuery": {
    "name": "Friends",
    "season": 3
  },
  "season": 3,
  "limit": 5
}

• phrase (required): The phrase to search
• videoQuery (required): Must include name. Can include imdb, season, episode, year, seasonEnd, episodeEnd, dubbed, animated, blackAndWhite
• season (optional): Limit search to specific season
• limit (optional): Max results
• Returns: { "result": { "episodes": [{ "season": 3, "episode": 15, "context": ["surrounding subtitle lines", ...] }, ...] } }

Scene Description Search

POST /api/find_by_scene_description

Search for a scene by visual description (not dialog).

{
  "_token": "...",
  "description": "Neo dodges bullets on a rooftop",
  "video": { "movieOrTVShowName": "The Matrix" },
  "nResults": 3,
  "nSkip": 0,
  "scoreThreshold": 0.4
}

• description (required): What happens in the scene visually. Do NOT include the movie name here.
• video (optional): Video query object to narrow search to a specific title
• nResults (required): Number of results to return
• nSkip (optional): Skip results (for pagination / "show me another")
• scoreThreshold (optional): Minimum similarity score 0-1. Use ~0.6 for specific scenes, ~0.3 for vague descriptions.
• Returns: { "result": { "results": [{ "query": { "movieOrTVShowName": "...", ... }, "time": "HH:MM:SS", "score": 0.85 }, ...], "warning": "..." } } or { "result": { "error": "..." } }

POST /api/request_indexing_for_scene_description

Request that a movie/show be indexed for scene description search. Use when find_by_scene_description returns no results for a known title.

{
  "_token": "...",
  "video": {
    "name": "The Matrix",
    "season": 1,
    "episode": 1
  }
}

• video.name (required): Movie/show name
• Other fields optional: imdb, season, episode, year, seasonEnd, episodeEnd, dubbed, animated, blackAndWhite
• Returns: { "result": { "requested": true } }

Transcription

Account

POST /api/check_quota

Check remaining search credits for the current month.

{ "_token": "..." }

• Returns: { "result": { "creditsRemaining": 42 } }

Error Handling

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

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.
• The download_by_time and extract_frame results are operation IDs. Never return these to the user as download links. Always poll until you get the actual URL.
• 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.