Subtitles Search API

Overview

The Subtitles Search API lets you search for movie and TV show subtitles by film name, file name, IDs (IMDb, TMDB, SubDL), season and episode numbers, type (movie or TV), release year, and language.

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

Method: GET

You can get a free API key from your SubDL account panel.

Request Parameters

Pass parameters in the URL query string. api_key is required, plus at least one search parameter (film_name, file_name, sd_id, imdb_id, or tmdb_id).

Successful Response

A successful response returns a JSON object with these fields:

• status: true on success.
• results: An array of movies or TV shows matching the search criteria.
• subtitles: An array of subtitles for the first movie/TV show in results.
• subtitles[].framerate: Framerate code of the upload (0 means default/unknown). See the framerate table in the Upload API docs.
• 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 returns a JSON object with these fields:

• status: false on failure.
• error: A message describing the reason for the failure.

Downloading Subtitles

Append the subtitle url from the response to the dl.subdl.com endpoint:

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

When unpack=1 is used, individual 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 authenticate download links with either an api_key query parameter or the x-api-key header. Authenticated downloads use your paid account-wide download quota instead of the anonymous limit of 300 downloads per day per IP.

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

curl "https://api.subdl.com/api/v1/subtitles?api_key=example-api-key&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"
        }
      ]
    }
  ]
}

JavaScript Example

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

Account Status

Use your API key to check your account, paid plan, per-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 per day. Paid API plans currently include 30,000 requests per day, 2,000 key-authenticated downloads per day, and up to 10 managed API keys.

Pro Autocomplete 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 per minute per key.

Pro API Translation

Paid users with translation quota can request a subtitle in a language that doesn't exist yet:

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 the job until download_ready is true, then download:

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 first looks for exact matches in the database, then falls back to broader criteria if necessary.
• Language codes must follow the supported language list to ensure accurate filtering.