OpenSubtitles.com Integration¶

OpenSubtitles API · OpenAPI schema

KeyPool exposes the core OpenSubtitles.com subtitle flow on the singular service route opensubtitle. The upstream OpenSubtitles API publishes an OpenAPI 3.0.3 schema; KeyPool's public spec below remains a routed, core-flow-only contract with the KeyPool authentication and session headers. KeyPool injects its pooled provider Api-Key and registered User-Agent; your application keeps its own OpenSubtitles login session.

Endpoint and team authentication¶

{YOUR_KEYPOOL_BASE_URL}/v1/opensubtitle

Every request uses the KeyPool team token:

Authorization: Bearer {KEYPOOL_TOKEN}

Authorization always means the KeyPool team token at the public edge. Do not replace it with an OpenSubtitles JWT.

Search subtitles¶

Search is available without a caller login session:

curl --get "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/subtitles" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  --data-urlencode "imdb_id=tt1375666" \
  --data-urlencode "languages=en"

Use the provider's documented search parameters for the exact content you need. The curated KeyPool surface intentionally excludes AI and upload endpoints. If OpenSubtitles canonicalizes a search with a redirect, KeyPool rewrites it to the same /v1/opensubtitle route, so clients never follow a provider-host URL. Clients that do not retain Authorization across redirects must resend the same KeyPool team token when requesting that returned URL.

Log in and retain the caller-owned session¶

Log in using your approved OpenSubtitles account. KeyPool forwards the request with its pooled Api-Key, returns the upstream JSON response, and never stores your password or raw JWT.

curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/login" \
  -X POST \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"username":"YOUR_OPENSUBTITLES_USERNAME","password":"YOUR_OPENSUBTITLES_PASSWORD"}'

Keep the returned token in your application session only. For the caller session endpoints below, send it in the dedicated header while retaining the KeyPool team token in Authorization:

X-KeyPool-OpenSubtitles-Session: Bearer {OPENSUBTITLES_JWT}

KeyPool stores only a SHA-256 fingerprint for 12 hours, bound to the selected provider credential and the standard or provider-approved VIP API host. It never stores your username, password, or JWT, and it does not accept a client-supplied upstream host.

Managed account credential group¶

Approved KeyPool users can obtain a RegBot-created OpenSubtitles account group when a client needs the upstream username and password:

curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/credentials/obtain" \
  -X POST \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}"

The response is audited and Cache-Control: no-store. It contains the provider api_key, username, password, and profile email only for the explicitly authorized service users. The group is AES-GCM encrypted at rest; ordinary admin credential listings never expose it. Most callers should use the normal proxy route and caller-owned login session instead.

Provider limits and account quotas¶

OpenSubtitles documents a login rate limit of one request per second. After login, continue using the returned base_url; VIP accounts can receive vip-api.opensubtitles.com and must continue sending the JWT. Authenticated download and translation allowances are account-specific and are returned by the login, user-info, and download responses. Do not infer those allowances from the pooled API key or from another account.

Source: OpenSubtitles API documentation.

Download subtitles¶

KeyPool supports downloading subtitles directly without requiring your application to obtain personal credentials or manage login sessions:

1. Standard API Download (returns download link)¶

Send POST /v1/opensubtitle/api/v1/download (or /download) with just your KeyPool team token. KeyPool automatically authenticates with its pooled accounts:

curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/download" \
  -X POST \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"file_id":12851909}'

Response:

{
  "link": "https://www.opensubtitles.com/download/...",
  "file_name": "movie.srt",
  "requests": 1,
  "remaining": 49
}

(Optional) If you maintain your own caller login session, you may still supply X-KeyPool-OpenSubtitles-Session: Bearer ${OPENSUBTITLES_JWT} to bind the download to your specific account.

2. Direct File Download (streams subtitle bytes)¶

KeyPool also exposes a direct download endpoint that fetches and streams the subtitle file content:

# Fetch raw subtitle file (.srt/.vtt) directly with filename attachment
curl -OJ "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/download/12851909" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}"

# Or pass ?download=1 to the POST endpoint
curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/download?download=1" \
  -X POST \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"file_id":12851909}'

Account information and logout¶

Account inspection and logout remain session-bound:

curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/infos/user" \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "X-KeyPool-OpenSubtitles-Session: Bearer ${OPENSUBTITLES_JWT}"

curl "${KEYPOOL_BASE_URL}/v1/opensubtitle/api/v1/logout" \
  -X DELETE \
  -H "Authorization: Bearer ${KEYPOOL_TOKEN}" \
  -H "X-KeyPool-OpenSubtitles-Session: Bearer ${OPENSUBTITLES_JWT}"

The session binding expires after 12 hours and is removed immediately after logout.

SDK samples¶

OpenSubtitles has no official client SDK in this repository. The maintained TypeScript and Python samples use raw HTTP and verify the provider formats endpoint through KeyPool:

sdk-samples/typescript/opensubtitle.test.ts
sdk-samples/python/test_opensubtitle.py

Interactive API Reference¶

Try the curated core flow in API Reference → OpenSubtitles.com.