New: SubDL API v2Cleaner endpoints, posters, AI translation, and a Pro tier — see the new developer docs →

Subtitles Search API Documentation (beta)

Overview

The Subtitles Search API allows users to search for movie or TV show subtitles based on various criteria such as film name, file name, specific IDs (IMDB, TMDB, SubDL), season and episode numbers, type (movie or TV), release year, and languages.

Endpoint: https://api.subdl.com/api/v1/subtitles Method: GET

Request Parameters

Send these one of these variables as GET URL

  • api_key (Required): the api key from subdl account
  • film_name (optional): Text search by film name.
  • file_name (optional): Search by file name.
  • sd_id (optional): Search by SubDL ID.
  • imdb_id (optional): Search by IMDb ID.
  • tmdb_id (optional): Search by TMDB ID.
  • season_number (optional): Specific season number for TV shows.
  • episode_number (optional): Specific episode number for TV shows.
  • type (optional): Type of the content, either movie or tv.
  • year (optional): Release year of the movie or TV show.
  • languages (optional): Comma-separated language codes for subtitle languages.
  • subs_per_page (optional): limit of subtitles will see in the results default is 10, (max can be 30)
  • comment (optional): send comment=1 to get author comment on subtitle
  • releases (optional): send releases=1 to get releases list on subtitle
  • hi (optional): send hi=1 to get is Hearing Impaired on subtitle
  • full_season (optional): send full_season=1 to get all full season subtitles
  • unpack (optional): send unpack=1 to include saved episode files for packed/full-season subtitles

Successful Response

A successful response will return a JSON object with the following fields:

  • status: A boolean indicating the success status (true).
  • results: An array of movies or TV shows matching the search criteria.
  • subtitles: An array of subtitles matching the search criteria for the first movie/TV show in the results.
  • subtitles[].framerate: Existing upload framerate code (0 means default/unknown).
  • subtitles[].fps: Human-readable FPS value such as 23.976, or null when unknown/default.
  • subtitles[].unpack_files: Returned only when unpack=1. Each item is one saved subtitle file from the pack and includes file_n_id, name, release_name, season, episode, language, hi, format, size, md5, and url.

Error Response

An error response is returned as a JSON object with the following fields:

  • status: A boolean indicating the success status (false).
  • error: Error message indicating the reason for failure.

Download link example

Add subtitle link to dl.subdl.com endpoint like this example:

https://dl.subdl.com/subtitle/3197651-3213944.zip

When unpack=1 is used, single raw subtitle files can be downloaded from the returned file URL:

https://dl.subdl.com/subtitle/{n_id}/{file_n_id}

Paid API users can pass the API key to download links with either api_key or the x-api-key header. This uses the paid account-wide download quota instead of the anonymous 300 downloads/day IP limit.

curl "https://dl.subdl.com/subtitle/3197651-3213944.zip?api_key=example-api-key"
curl -H "x-api-key: example-api-key" "https://dl.subdl.com/subtitle/{n_id}/{file_n_id}"

Usage Example

Request

{
  "query": {
    "api_key": "abcdefghisubdl",
    "film_name": "Inception",
    "type": "movie",
    "languages": "EN,FR",
    "unpack": "1"
  }
}

Response Body

{
  "status": true,
  "results": [
    {
      "imdb_id": "tt1375666",
      "tmdb_id": 27205,
      "type": "movie",
      "name": "Inception",
      "sd_id": 123456,
      "first_air_date": null,
      "year": 2010
    }
  ],
  "subtitles": [
    {
      "release_name": "Season Pack",
      "name": "Season.Pack.zip",
      "url": "/subtitle/3197651-3213944.zip",
      "season": 1,
      "episode": 1,
      "framerate": 2,
      "fps": "23.976",
      "episode_from": 1,
      "episode_end": 10,
      "full_season": true,
      "unpack_files": [
        {
          "file_n_id": "file123",
          "name": "Episode.One.srt",
          "release_name": "Episode One",
          "season": 1,
          "episode": 1,
          "language": "EN",
          "hi": false,
          "format": "srt",
          "size": 12345,
          "md5": "example-md5",
          "url": "/subtitle/parent_n_id/file123"
        }
      ]
    }
  ]
}

Account Status

Use your public API key to check account, paid plan, active key usage, and account-wide request/download quotas:

curl "https://api.subdl.com/api/v1/me?api_key=example-api-key"

Free API keys get 2,000 requests/day. Paid API plans currently include 30,000 requests/day, 2,000 key-authenticated downloads/day, and up to 10 managed API keys.

Pro Auto And Search API

Paid API users can use higher-limit autocomplete and search endpoints:

curl "https://api.subdl.com/api/v1/auto?api_key=example-api-key&query=matrix&type=movie"
curl "https://api.subdl.com/api/v1/search?api_key=example-api-key&query=lost&type=tv"

These endpoints require an active paid API subscription, count toward the account-wide request quota, and allow up to 600 requests/minute per key.

Pro API Translation

Paid users with translation quota can request a missing subtitle language:

curl -X POST "https://api.subdl.com/api/v1/pro/translate/subtitles?api_key=example-api-key" \
  -H "Content-Type: application/json" \
  -d '{"n_id":"subtitle-n-id","file_n_id":"optional-file-id","target_language":"FA"}'

The response returns a request_id immediately. Poll until download_ready is true:

curl "https://api.subdl.com/api/v1/pro/translate/jobs/{request_id}?api_key=example-api-key"
curl "https://api.subdl.com/api/v1/pro/translate/jobs/{request_id}/download?api_key=example-api-key"

Status values are queued, running, publishing, translated, published, reused, and failed.

Translation error responses include a stable error code plus a human-readable message:

  • translation_not_entitled (HTTP 402): no active paid plan with translation quota. Both SubDL Plus and SubDL Pro include a monthly translation quota.
  • translation_quota_exhausted (HTTP 429): the monthly translation quota is used up; it resets on the 1st of each month (UTC).

Repeating a request for the same source subtitle, target language, and tone returns the finished job immediately with reused: true and does not consume quota.

Notes

  • API rate limiting is applied account-wide, with per-key counters shown in the dashboard.
  • The search is optimized to first look for exact matches in the database and then proceed with broader criteria if necessary.
  • The language codes should follow the specific format provided in the API documentation to ensure accurate filtering of subtitles.

This API provides a powerful tool for developers to integrate subtitle search functionality into their applications, offering extensive filtering options to cater to a wide range of user preferences.

CURL Example Request

curl -X GET "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=EN&unpack=1"

JavaScript code Example Request

fetch(
  "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&film_name=Inception&type=movie&languages=ar&unpack=1",
  {
    method: "GET",
    headers: {
      Accept: "application/json",
    },
  }
)
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error("Error:", error))