Subtitles are an indispensable part of the modern media experience. They bridge language barriers, enhance accessibility for the hearing impaired, and aid language learners worldwide. At the heart of subtitle accessibility lies OpenSubtitles, one of the largest and most popular online repositories for subtitle files. But OpenSubtitles is more than just a website; it offers a powerful REST API that allows developers to integrate its vast subtitle database directly into their applications.
Whether you're building a media player, a content management system, a language learning tool, or any application that could benefit from subtitle integration, the OpenSubtitles API provides the necessary tools. This comprehensive guide will walk you through everything you need to know to effectively utilize the OpenSubtitles API, from initial setup and authentication to searching, downloading, translating subtitles, and adhering to best practices.
Want an integrated, All-in-One platform for your Developer Team to work together with maximum productivity?
Apidog delivers all your demans, and replaces Postman at a much more affordable price!
What is the OpenSubtitles API?
The OpenSubtitles API is a set of programming interfaces that allows developers to programmatically interact with the OpenSubtitles database. Instead of manually searching and downloading subtitles from the website, applications can use the API to perform these actions automatically. This opens up a world of possibilities for creating seamless and feature-rich user experiences.
Key Capabilities:
Search: Find subtitles based on various criteria like movie/show title, IMDB ID, TMDB ID, file hash, language, and more. Download: Retrieve specific subtitle files identified through search results. AI Translation: Leverage artificial intelligence to translate existing subtitles into different languages. Information Retrieval: Access metadata about subtitles and media.
Getting Started: Your First Steps
Before you can make calls to the API, there are a few prerequisites and foundational concepts to understand.
1. API Endpoint:
All interactions with the OpenSubtitles REST API happen through a single base URL:
https://api.opensubtitles.com/api/v1
All specific endpoints (like searching or downloading) are appended to this base URL.
2. Registration and API Key:
Accessing the API requires authentication. The primary method involves using an API Key.
Register: You first need an account on OpenSubtitles. If you don't have one, register on their website. Obtain API Key: Once registered, you'll need to generate an API Key. This is typically done through your user profile or a dedicated developer section on the OpenSubtitles website. Keep your API Key secure, as it identifies your application's requests.
3. Authentication:
The API supports two main authentication methods:
API Key: The simplest method. Include your API Key in the Api-Key header of every request. Api-Key: YOUR_API_KEY JWT Token: For potentially accessing more user-specific features or different rate limits (depending on API design), you can log in via the /login endpoint (covered later) to obtain a JSON Web Token (JWT). This token is then included in the Authorization header as a Bearer token. Authorization: Bearer YOUR_JWT_TOKEN
You still generally need to provide the Api-Key header even when using a JWT token for application identification.
4. Essential Headers:
Besides authentication headers, every API request must include:
Content-Type: For requests with a body (like POST requests), this should typically be application/json. Content-Type: application/json **User-Agent:** This is crucial. The API requires a descriptive User-Agent string that identifies your application. Vague or default User-Agents (like python-requests) might be blocked. A good format is YourAppName v1.0. User-Agent: MySubtitleApp v1.2.3
5. Rate Limiting:
Like most public APIs, OpenSubtitles enforces rate limits to ensure fair usage and server stability. Exceeding these limits will result in error responses (often 429 Too Many Requests). Pay close attention to the following response headers to manage your request rate:
X-RateLimit-Limit: The maximum number of requests allowed in the current window. X-RateLimit-Remaining: The number of requests remaining in the current window. X-RateLimit-Reset: The timestamp (often Unix epoch time) when the rate limit window resets. Retry-After: If you receive a 429 error, this header indicates how many seconds you should wait before retrying.
Implementing logic in your application to respect these headers is essential for reliable operation.
Authentication Deep Dive: The /login Endpoint
While using just the API Key is often sufficient, the /login endpoint allows your application to authenticate as a specific OpenSubtitles user, obtaining a JWT.
Endpoint: POST /login
Purpose: To exchange user credentials (username/password) for a JWT authentication token.
Request Body:
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
Headers:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Successful Response (Example):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // This is the JWT
"status": 200
}
Using the JWT:
Once obtained, include this token value in the Authorization header for subsequent requests:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Using JWT might grant access to user-specific download quotas or other features tied to the user's account level or VIP status. Remember that JWTs typically have an expiration time, so you might need to re-authenticate periodically.
Core Functionality: Searching for Subtitles (/subtitles)
This is perhaps the most frequently used endpoint. It allows you to query the vast OpenSubtitles database.
Endpoint: GET /subtitles
Purpose: To find subtitles based on various search criteria.
Authentication: Requires Api-Key header (and optionally Authorization: Bearer <token>).
Key Query Parameters:
The power of the search lies in its flexible query parameters. You can combine these as needed:
query=<string>: Search by movie or episode title (e.g., query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Search using the IMDb ID (e.g., imdb_id=tt0133093). This is often more accurate than query. tmdb_id=<integer>: Search using The Movie Database (TMDb) ID (e.g., tmdb_id=603). Also very accurate. parent_tmdb_id=<integer>: For searching episodes, use the TMDb ID of the show (e.g., parent_tmdb_id=1399 for Game of Thrones). season_number=<integer>: Combine with parent_tmdb_id (or imdb_id of the show) to find subtitles for a specific season. episode_number=<integer>: Combine with parent_tmdb_id (or imdb_id of the show) and season_number for a specific episode. languages=<string>: Filter by language codes (comma-separated, e.g., languages=en,es, languages=fr). Use ISO 639-2B codes (like eng, spa, fre). moviehash=<string>: Search using a unique hash calculated from the video file. This provides the most accurate match if you have the video file itself. Calculating this hash usually requires specific libraries or tools. type=<string>: Filter by type (movie or episode). hearing_impaired=<include|exclude|only>: Filter for subtitles designed for the hearing impaired. machine_translated=<include|exclude|only>: Filter based on whether subtitles were machine-translated. ai_translated=<include|exclude|only>: Filter based on whether subtitles were translated using the API's AI feature. order_by=<field>: Sort results (e.g., order_by=download_count). order_direction=<asc|desc>: Specify sort direction.
Example Search Request (Finding English subtitles for "Inception" via TMDb ID):
GET /api/v1/subtitles?tmdb_id=27205&languages=en HTTP/1.1
Host: api.opensubtitles.com
Api-Key: YOUR_API_KEY
User-Agent: MySubtitleApp v1.0
Accept: application/json
Interpreting Search Results:
The response is a JSON object containing a data array. Each element in the array represents a subtitle match.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // Subtitle ID (useful but not for download)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // Legacy ID
"language": "en",
"download_count": 500000,
"new_download_count": 150000,
"hearing_impaired": false,
"hd": true,
"format": "srt",
"fps": 23.976,
"votes": 120,
"points": 10,
"ratings": 8.5,
"from_trusted": true,
"foreign_parts_only": false,
"ai_translated": false,
"machine_translated": false,
"upload_date": "2010-10-25T12:00:00Z",
"release": "Inception.2010.720p.BluRay.x264-REWARD",
"comments": "Sync and Corrected by ...",
"legacy_subtitle_id": 987654,
"uploader": {
"uploader_id": 54321,
"name": "UploaderName",
"rank": "Administrator"
},
"feature_details": { // Information about the movie/episode
"feature_id": 5555,
"feature_type": "Movie",
"year": 2010,
"title": "Inception",
"movie_name": "Inception",
"imdb_id": "tt1375666",
"tmdb_id": 27205
},
"url": "<https://www.opensubtitles.org/en/subtitles/1234567/inception-en>",
"related_links": [
// ... links to related content ...
],
"files": [ // CRUCIAL: This array contains the file(s) for this subtitle entry
{
"file_id": 998877, // <<< THIS is the ID needed for the /download endpoint
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Potentially more files if it's a multi-part subtitle (e.g., CD1, CD2)
]
}
},
// ... more subtitle results ...
]
}
The most important piece of information needed for downloading is the file_id found within the attributes.files array. Note that a single subtitle entry (data array element) might contain multiple files (e.g., for older CD1/CD2 releases). Your application should typically select the appropriate file_id based on criteria like cd_number or file_name.
Core Functionality: Downloading Subtitles (/download)
Once you have identified the desired subtitle file using the /subtitles endpoint and extracted its file_id, you can use the /download endpoint to get a temporary link to the actual subtitle file.
Endpoint: POST /download
Purpose: To request a download link for a specific subtitle file.
Authentication: Requires Api-Key header and valid user authentication (either a logged-in JWT token in the Authorization header or potentially specific API key permissions, depending on API policy – often JWT is preferred/required for downloads to track quotas).
Request Body:
{
"file_id": 998877 // The file_id obtained from the search results
// Optional parameters like "sub_format", "file_name", "in_fps", "out_fps" might be available for on-the-fly conversion
}
Headers:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Likely required) User-Agent: YourAppName v1.0
Successful Response (Example):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // Temporary download URL
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Number of available requests for this specific link/file? (Check docs)
"remaining": 95, // User's remaining download quota for the day/period
"message": "Download count successful.",
"reset_time": "2023-10-27T12:00:00Z", // When the download quota might reset
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Handling the Download:
Make the POST request to /download with the correct file_id. Check the response status code for success (e.g., 200 OK). Extract the link value from the JSON response. Make a standard HTTP GET request to this link URL. This request does not typically require the API Key or Authorization headers, as the link itself is pre-authorized. The response to the GET request on the link URL will be the actual subtitle file content (e.g., the text of the SRT file). Save this content to a file (e.g., using the provided file_name).
Important: The download links (link) are usually temporary and may expire after a short period or a certain number of uses. Do not store these links for long-term use; fetch a fresh link via the /download endpoint each time a download is needed. Also, monitor the remaining download count to avoid exhausting the user's quota.
Advanced Features: AI Translation (/ai-translation)
A more recent addition to the OpenSubtitles toolkit is the AI-powered translation feature.
Endpoint: POST /ai-translation (or similar, check exact endpoint in docs)
Purpose: To translate an existing subtitle file into another language using AI models.
How it Works (Conceptual):
You likely provide the file_id of the source subtitle you want to translate. You specify the target_language (e.g., target_language=de for German). The API processes the request, potentially queuing the translation job. The response might indicate the job status or provide a new file_id or download link for the translated subtitle once completed.
Use Cases:
Making subtitles available in languages not originally present in the database. Providing users with on-demand translation options within your application.
Considerations:
AI translations may have associated costs or specific rate limits/quotas, potentially tied to VIP or subscription tiers. The quality of AI translation can vary depending on the language pair and the complexity of the source text. This feature might require specific user permissions or subscription levels. Consult the API documentation for details on usage, parameters, and limitations.
Best Practices for API Integration
To ensure your application interacts smoothly and responsibly with the OpenSubtitles API, follow these best practices:
Cache Responses: Especially for search results (/subtitles) that don't change rapidly. If a user searches for the same movie/episode multiple times, serve the cached result instead of hitting the API repeatedly. Implement intelligent caching with reasonable expiration times. Respect Rate Limits: Actively monitor the X-RateLimit-* and Retry-After headers. Implement exponential backoff strategies if you hit the limit (wait longer after repeated rate-limiting). Do not aggressively poll the API. Use Specific Identifiers: Whenever possible, search using imdb_id or tmdb_id instead of query. These provide much more accurate results and reduce ambiguity. Use moviehash for the highest accuracy if the video file is available. Provide a Clear User-Agent: Use a unique and descriptive User-Agent string (e.g., MyMediaPlayerApp/2.1 (contact@myapp.com)). This helps OpenSubtitles identify traffic sources and troubleshoot issues. Generic agents may be blocked. Handle Errors Gracefully: Check HTTP status codes for every response. Implement logic to handle common errors like 401 Unauthorized (invalid API Key/JWT), 403 Forbidden (permission denied), 404 Not Found, 429 Too Many Requests, and 5xx server errors. Provide informative feedback to the user. Manage Download Quotas: Be mindful of the daily/periodic download limits associated with the user's account (or API key). Inform users if they are approaching or have exceeded their quota. Use the remaining field in the /download response. Optimize Searches: Don't request unnecessary data. Use parameters like languages, type, hearing_impaired etc., to narrow down results server-side rather than filtering large datasets client-side. Secure Your API Key: Treat your API Key like a password. Do not embed it directly in client-side code. Store it securely on your server.
Wrappers, Scripts, and Community Resources
While this guide covers direct API interaction, the OpenSubtitles ecosystem often includes community-developed resources.
API Wrappers: Look for libraries or SDKs for your programming language (e.g., Python, JavaScript, Java) on platforms like GitHub or package managers (PyPI, npm). These wrappers can simplify API calls, handle authentication, and parse responses. Scripts: Various command-line tools or scripts might exist for interacting with the API, useful for automation or quick lookups. Forums/Communities: Check OpenSubtitles forums or related developer communities for discussions, examples, and potential third-party tools utilizing the API.
Using a well-maintained wrapper can significantly speed up development, but understanding the underlying API calls (as described in this guide) remains crucial for troubleshooting and advanced usage.
API Subscription and Pricing
OpenSubtitles typically offers different access levels to its API:
Free Tier: Usually provides basic access with stricter rate limits and download quotas. Suitable for low-volume applications or development/testing. VIP/Paid Tiers: Offer significantly higher rate limits, larger download quotas, access to premium features (like potentially AI Translation or faster support), and are intended for commercial or high-traffic applications.
Refer to the official OpenSubtitles API documentation or website for the most current details on subscription plans, pricing, and the specific limits/features associated with each tier. Choose the plan that best matches your application's expected usage and feature requirements.
Conclusion
The OpenSubtitles API is a powerful gateway to one of the world's largest subtitle collections. By understanding its structure, authentication methods, core endpoints like /subtitles and /download, and adhering to best practices, developers can seamlessly integrate subtitle functionality into their applications. From simple lookups in media players to complex features involving AI translation, the API provides the building blocks for innovative and user-friendly experiences. Remember to consult the official OpenSubtitles API documentation for the most up-to-date endpoint details, parameters, and policies as you embark on your development journey. Happy coding!
