Skip to content

SubDL Integration

SubDL API

KeyPool provides the SubDL search and download flow with a KeyPool team token. It selects and injects the upstream api_key server-side; clients must never send one.

Endpoint and authentication

{YOUR_KEYPOOL_BASE_URL}/v1/subdl

Send your KeyPool team token on every request:

Authorization: Bearer {KEYPOOL_TOKEN}

Do not add an api_key query parameter. KeyPool removes client-supplied credential parameters and attaches the selected SubDL key only when it calls the provider.

Search subtitles

Use SubDL's standard search parameters. This example searches an English movie title and asks for unpacked file metadata:

curl --get "${KEYPOOL_BASE_URL}/v1/subdl/api/v1/subtitles" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  --data-urlencode "film_name=Inception" \
  --data-urlencode "type=movie" \
  --data-urlencode "languages=EN" \
  --data-urlencode "subs_per_page=30" \
  --data-urlencode "unpack=true"

You can also use provider-supported identifiers such as imdb_id or tmdb_id instead of a title. KeyPool preserves SubDL response fields, except that known subtitle download URLs are rewritten to KeyPool URLs.

Download a returned subtitle

The url field in a successful search response already points back to KeyPool, for example:

{YOUR_KEYPOOL_BASE_URL}/v1/subdl/subtitle/example.zip

Follow that URL with the same team token. KeyPool forwards the download only to the allowlisted dl.subdl.com host and injects the provider key there. Relative or dl.subdl.com URLs inside unpack_files are rewritten the same way.

Account check

curl "${KEYPOOL_BASE_URL}/v1/subdl/api/v1/me" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}"

The account endpoint is available for an on-demand compatibility check. KeyPool does not configure it as an automatic health probe because SubDL credentials are quota-limited.

Free-plan limits

SubDL's official API documentation currently lists these free-plan limits:

Resource Free-plan limit
API requests 2,000 per day
Anonymous downloads 300 per day per IP

The free request quota is account-wide, while the dashboard exposes per-key counters. Key-authenticated download quotas are available to paid accounts and must not be assumed for a free key. SubDL does not publish a free-plan RPM value in the API documentation; use the account endpoint and dashboard for current usage and quota state.

Source: SubDL search and download API documentation.

Notes

  • The acquisition service is subdl in both RegBot and KeyPool.
  • RegBot pushes new credentials; KeyPool owns runtime eligibility, health, and circuit breakers.
  • Use the documented SubDL search parameters, but never include a client-held provider api_key.

SDK samples

SubDL has no official client SDK in this repository, so the maintained TypeScript and Python samples use raw HTTP and exercise the same KeyPool search and rewritten-download flow:

  • sdk-samples/typescript/subdl.test.ts
  • sdk-samples/python/test_subdl.py

Interactive API Reference

Try the curated search, download, and account flows in API Reference → SubDL.