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.

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.

Interactive API Reference

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