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:

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:

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.