SubDL Developer API

Build subtitle apps on the SubDL API

Q: How do I get a SubDL API key?

Create a free SubDL account, open your panel, and generate an API key from the API section. The free tier includes 2,000 searches and 50 downloads per day.

Q: Is the SubDL API free?

Yes. The free tier allows 2,000 searches and 50 downloads per day. SubDL Pro raises this to 30,000 searches and 2,000 downloads per day, plus AI subtitle translation.

Q: What can I build with the SubDL API?

Search 4M+ subtitles across 500K+ TMDB-matched movies and TV shows, download SRT files, and use AI subtitle translation — ideal for media players, Bazarr-style tools, and apps.

Search 4M+ subtitles matched to a TMDB-clean database, download season packs and single episodes, and translate any subtitle with AI in under 60 seconds.

Get an API key View Pro plans

🎬TMDB-matched database

Every title resolves to clean TMDB/IMDb ids — no fuzzy guessing.

🎞️500K movies & TV series

Half a million titles indexed and ready to search.

📚4M+ subtitles

One of the largest subtitle catalogs, across dozens of languages.

🚀~50ms response time

Cached, edge-fast search responses for snappy autocomplete.

🗄️Full Subscene legacy archive

The complete Subscene back-catalog, preserved and searchable.

🌐Alternative names, every language

Match titles by their localized and alternative names worldwide.

📦Season packs & episodes

Pull a whole season in one call, or a single episode.

🔎Search by IMDb

Look up titles and subtitles directly by IMDb id or URL.

🌸Anime-friendly subtitles

Strong anime coverage with release-aware matching and tone presets.

⚡AI translation < 60s

Translate a full subtitle file into any language in under a minute.

🧠AI filename search

Drop a messy release filename and get the right match.

👑 AI & higher limits are SubDL Pro

Search and download work on a free key. AI translation, AI transcription, AI filename search, 30,000 requests/day and 2,000 downloads/day require SubDL Pro.

Upgrade to SubDL Pro

Quickstart

Authenticate every request with your API key in an Authorization: Bearer header (or X-API-Key). The legacy ?api_key= query is still accepted for download links. Base URL: https://api.subdl.com

# Your first request
curl "https://api.subdl.com/api/v2/movies/search?q=dune" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

Search

GET/api/v2/movies/search

Movie & TV search

Title search for autocomplete or a search page. Returns posters and matched ids (sd_id, imdb_id, tmdb_id).

Parameters

q *Search query (min 2 chars). Accepts an IMDb id/url too.

typeFilter: movie or tv.

limitMax results, 1–30 (default 10). Small values behave like autocomplete.

curl "https://api.subdl.com/api/v2/movies/search?q=dune&type=movie&limit=5" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

Example response

{
  "results": [
    {
      "sd_id": "sd123456",
      "type": "movie",
      "name": "Dune: Part Two",
      "original_name": "Dune: Part Two",
      "year": 2024,
      "imdb_id": "tt15239678",
      "tmdb_id": 693134,
      "poster_url": "https://.../poster.jpg",
      "subtitles_count": 412,
      "url": "https://subdl.com/subtitle/sd123456/dune-part-two"
    }
  ]
}

GET/api/v2/files/search

Filename search

Pass a release filename and get the matched title plus its subtitles. Ideal for media managers scanning a library.

Parameters

filename *The release filename, e.g. Dune.Part.Two.2024.2160p.BluRay.x265-GROUP.mkv

languagesComma-separated language codes, e.g. en,fa,ar.

subs_per_pageSubtitles per page (max 30).

curl "https://api.subdl.com/api/v2/files/search?filename=Dune.Part.Two.2024.2160p.BluRay.x265-GROUP.mkv&languages=en,fa" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

GET/api/v2/subtitles/search

Subtitle search

Fast exact subtitle search by id or title. Provide one of sd_id, imdb_id, tmdb_id, film_name, or file_name. Add unpack=1 to receive per-file (non-zip) download urls.

Parameters

sd_id | imdb_id | tmdb_id *One title key. (Or film_name / file_name.)

typemovie or tv. Required when using tmdb_id — a TMDB id is only unique together with the media type.

languagesComma-separated language codes.

season / episodeFor TV. Use full_season=1 for a season pack.

unpack1 to expand archives into exact single-file download urls.

curl "https://api.subdl.com/api/v2/subtitles/search?imdb_id=tt15239678&languages=en,fa" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

Download

GET/api/v2/subtitles/{nId}/download

Download a subtitle

Address a subtitle by its nId. format=zip (default) returns the archive; format=file returns the exact single (non-zip) file when the archive has one obvious file.

Parameters

nId *Subtitle nId (from a search result).

formatzip (default) or file (exact non-zip file).

curl "https://api.subdl.com/api/v2/subtitles/abcdef/download?format=file" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

AI

POST/api/v2/ai/translations👑 SubDL Pro

Start a translation

Translate an existing subtitle into any language with AI, typically in under 60 seconds. Returns a request_id; poll the job until download_ready.

Parameters

n_id *Subtitle nId to translate.

target_language *Target language code, e.g. FA.

toneOptional: faithful, formal, casual, cinematic_action, comedic_fun, anime.

curl -X POST "https://api.subdl.com/api/v2/ai/translations" \
  -H "Authorization: Bearer $SUBDL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n_id":"abcdef","target_language":"FA","tone":"faithful"}'

GET/api/v2/ai/translations👑 SubDL Pro

List translation jobs

List your translation jobs with their status and progress.

curl "https://api.subdl.com/api/v2/ai/translations?page=1" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

GET/api/v2/ai/translations/{id}👑 SubDL Pro

Translation job status

Poll a single job for progress, ETA, and download_ready.

curl "https://api.subdl.com/api/v2/ai/translations/req_123" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

POST/api/v2/ai/transcriptions👑 SubDL ProBeta

AI transcribe

Generate subtitles from a media file with speech-to-text. In beta — shape may change.

curl -X POST "https://api.subdl.com/api/v2/ai/transcriptions" \
  -H "Authorization: Bearer $SUBDL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_url":"https://.../episode.mp3","language":"en"}'

GET/api/v2/ai/filename-search👑 SubDL ProBeta

AI filename search

Use AI to resolve a messy or ambiguous release filename to the best TMDB match. In beta.

curl "https://api.subdl.com/api/v2/ai/filename-search?filename=that.movie.2021.WEBRip.mkv" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

Account

GET/api/v2/me

Account & usage

Your plan plus separated counters (search/day, downloads/day, AI/month) with reset times. Does not count against your search quota.

curl "https://api.subdl.com/api/v2/me" \
  -H "Authorization: Bearer $SUBDL_API_KEY"

Example response

{
  "plan": { "is_pro": false, "name": "Free" },
  "usage": {
    "search":    { "used": 12, "limit": 2000, "remaining": 1988, "period": "day" },
    "downloads": { "used": 3,  "limit": 50,   "remaining": 47,   "period": "day" },
    "ai": {
      "translations": { "eligible": false, "free_trial_per_month": 1, "period": "month" }
    }
  },
  "upgrade_url": "https://subdl.com/pro"
}

Errors & rate limits

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Errors share one shape:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily request quota exceeded.",
    "docs_url": "https://subdl.com/developers#errors"
  }
}

Tier	Search / day	Downloads / day	AI
Free	2,000	50	1 free trial / feature / month
SubDL Pro	30,000	2,000	60 translations / month

Frequently asked questions

How do I get a SubDL API key?

Create a free SubDL account, open your panel, and generate an API key from the API section. The free tier includes 2,000 searches and 50 downloads per day.

Is the SubDL API free?

Yes. The free tier allows 2,000 searches and 50 downloads per day. SubDL Pro raises this to 30,000 searches and 2,000 downloads per day, plus AI subtitle translation.

What can I build with the SubDL API?

Search 4M+ subtitles across 500K+ TMDB-matched movies and TV shows, download SRT files, and use AI subtitle translation — ideal for media players, Bazarr-style tools, and apps.

Looking for the original v1 docs? Open the classic API docs