Phụ đề là một phần không thể thiếu trong trải nghiệm truyền thông hiện đại. Chúng giúp vượt qua rào cản ngôn ngữ, tăng cường khả năng tiếp cận cho những người khiếm thính, và hỗ trợ việc học ngôn ngữ cho người học trên toàn cầu. Tại trái tim của khả năng truy cập phụ đề là OpenSubtitles, một trong những kho lưu trữ phụ đề trực tuyến lớn nhất và phổ biến nhất. Nhưng OpenSubtitles không chỉ là một trang web; nó cung cấp một REST API mạnh mẽ cho phép các lập trình viên tích hợp cơ sở dữ liệu phụ đề rộng lớn của nó trực tiếp vào ứng dụng của họ.
Dù bạn đang xây dựng một trình phát media, một hệ thống quản lý nội dung, một công cụ học ngôn ngữ hay bất kỳ ứng dụng nào có thể hưởng lợi từ việc tích hợp phụ đề, API OpenSubtitles cung cấp các công cụ cần thiết. Hướng dẫn toàn diện này sẽ hướng dẫn bạn tất cả những gì bạn cần biết để sử dụng hiệu quả API OpenSubtitles, từ thiết lập ban đầu và xác thực đến tìm kiếm, tải xuống, dịch phụ đề và tuân thủ các thực hành tốt nhất.
Bạn muốn một nền tảng tích hợp, Tất cả trong Một cho đội ngũ phát triển của bạn làm việc cùng nhau với năng suất tối đa?
Apidog đáp ứng tất cả nhu cầu của bạn và thay thế Postman với giá cả phải chăng hơn nhiều!
API OpenSubtitles là gì?
API OpenSubtitles là một tập hợp các giao diện lập trình cho phép các lập trình viên tương tác với cơ sở dữ liệu OpenSubtitles một cách chương trình. Thay vì tìm kiếm và tải xuống phụ đề thủ công từ trang web, các ứng dụng có thể sử dụng API để thực hiện những hành động này tự động. Điều này mở ra một thế giới khả năng tạo ra trải nghiệm người dùng mượt mà và phong phú tính năng.
Các khả năng chính:
Tìm kiếm: Tìm phụ đề dựa trên các tiêu chí khác nhau như tiêu đề phim/show, ID IMDB, ID TMDB, hash tệp, ngôn ngữ, và nhiều hơn nữa. Tải xuống: Lấy các tệp phụ đề cụ thể được xác định qua kết quả tìm kiếm. Dịch AI: Tận dụng trí tuệ nhân tạo để dịch phụ đề hiện có sang các ngôn ngữ khác nhau. Khôi phục thông tin: Truy cập metadata về phụ đề và phương tiện.
Bắt đầu: Những bước đầu tiên của bạn
Trước khi bạn có thể thực hiện các gọi đến API, có một số điều kiện tiên quyết và khái niệm cơ bản cần hiểu.
1. Điểm cuối API:
Tất cả các tương tác với API REST OpenSubtitles diễn ra thông qua một URL cơ sở duy nhất:
https://api.opensubtitles.com/api/v1
Tất cả các điểm cuối cụ thể (như tìm kiếm hoặc tải xuống) được thêm vào URL cơ sở này.
2. Đăng ký và Khóa API:
Truy cập API yêu cầu xác thực. Phương pháp chính bao gồm việc sử dụng một Khóa API.
Đăng ký: Bạn cần một tài khoản trên OpenSubtitles. Nếu bạn chưa có, hãy đăng ký trên trang web của họ. Nhận Khóa API: Sau khi đăng ký, bạn sẽ cần tạo một Khóa API. Điều này thường được thực hiện qua hồ sơ người dùng của bạn hoặc một phần nhà phát triển chuyên dụng trên trang web OpenSubtitles. Giữ Khóa API của bạn được bảo mật, vì nó xác định các yêu cầu của ứng dụng của bạn.
3. Xác thực:
API hỗ trợ hai phương pháp xác thực chính:
Khóa API: Phương pháp đơn giản nhất. Bao gồm Khóa API của bạn trong tiêu đề Api-Key của mỗi yêu cầu. Api-Key: YOUR_API_KEY JWT Token: Để có thể truy cập nhiều tính năng cụ thể cho người dùng hơn hoặc giới hạn tỷ lệ khác nhau (tùy thuộc vào thiết kế API), bạn có thể đăng nhập qua điểm cuối /login (được đề cập sau) để nhận được JSON Web Token (JWT). Token này sau đó được bao gồm trong tiêu đề Authorization dưới dạng một token Bearer. Authorization: Bearer YOUR_JWT_TOKEN
Bạn vẫn cần cung cấp tiêu đề Api-Key ngay cả khi sử dụng token JWT để xác định ứng dụng.
4. Các tiêu đề cần thiết:
Ngoài các tiêu đề xác thực, mỗi yêu cầu API phải bao gồm:
Content-Type: Đối với các yêu cầu có nội dung (như yêu cầu POST), điều này thường nên là application/json. Content-Type: application/json **User-Agent:** Điều này là rất quan trọng. API yêu cầu một chuỗi User-Agent mô tả xác định ứng dụng của bạn. Các User-Agent mơ hồ hoặc mặc định (như python-requests) có thể bị chặn. Một định dạng tốt là YourAppName v1.0. User-Agent: MySubtitleApp v1.2.3
5. Giới hạn tỷ lệ:
Như hầu hết các API công cộng, OpenSubtitles cũng áp dụng các giới hạn tỷ lệ để đảm bảo sử dụng công bằng và ổn định của máy chủ. Vi phạm những giới hạn này sẽ dẫn đến các phản hồi lỗi (thường là 429 Too Many Requests). Hãy chú ý đến các tiêu đề phản hồi sau đây để quản lý tỷ lệ yêu cầu của bạn:
X-RateLimit-Limit: Số lượng yêu cầu tối đa cho phép trong cửa sổ hiện tại. X-RateLimit-Remaining: Số lượng yêu cầu còn lại trong cửa sổ hiện tại. X-RateLimit-Reset: Dấu thời gian (thường là thời gian epoch Unix) khi cửa sổ giới hạn tỷ lệ được đặt lại. Retry-After: Nếu bạn nhận được lỗi 429, tiêu đề này chỉ ra số giây bạn nên chờ trước khi thử lại.
Triển khai logic trong ứng dụng của bạn để tôn trọng các tiêu đề này là rất quan trọng để hoạt động đáng tin cậy.
Đi sâu vào xác thực: Điểm cuối /login
Khi chỉ sử dụng Khóa API thường đủ, điểm cuối /login cho phép ứng dụng của bạn xác thực dưới dạng một người dùng OpenSubtitles cụ thể, nhận được một JWT.
Điểm cuối: POST /login
Mục đích: Để trao đổi thông tin người dùng (tên người dùng/mật khẩu) để lấy một mã thông báo xác thực JWT.
Nội dung yêu cầu:
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
Tiêu đề:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Phản hồi thành công (Ví dụ):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Đây là JWT
"status": 200
}
Sử dụng JWT:
Ngay khi có, bao gồm giá trị token này trong tiêu đề Authorization cho các yêu cầu tiếp theo:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Sử dụng JWT có thể cấp quyền truy cập vào các hạn ngạch tải xuống cụ thể cho người dùng hoặc các tính năng khác liên quan đến cấp độ tài khoản của người dùng hoặc trạng thái VIP. Hãy nhớ rằng JWT thường có thời gian hết hạn, vì vậy bạn có thể cần phải xác thực lại định kỳ.
Chức năng chính: Tìm kiếm phụ đề (/subtitles)
Đây có lẽ là điểm cuối được sử dụng thường xuyên nhất. Nó cho phép bạn truy vấn cơ sở dữ liệu OpenSubtitles rộng lớn.
Điểm cuối: GET /subtitles
Mục đích: Để tìm phụ đề dựa trên các tiêu chí tìm kiếm khác nhau.
Xác thực: Yêu cầu tiêu đề Api-Key (và tùy chọn Authorization: Bearer <token>).
Các tham số truy vấn chính:
Sức mạnh của tìm kiếm nằm ở các tham số truy vấn linh hoạt. Bạn có thể kết hợp chúng như cần thiết:
query=<string>: Tìm kiếm theo tiêu đề phim hoặc tập (ví dụ: query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Tìm kiếm theo ID IMDb (ví dụ: imdb_id=tt0133093). Điều này thường chính xác hơn so với query. tmdb_id=<integer>: Tìm kiếm theo ID The Movie Database (TMDb) (ví dụ: tmdb_id=603). Cũng rất chính xác. parent_tmdb_id=<integer>: Để tìm kiếm các tập, sử dụng ID TMDb của chương trình (ví dụ: parent_tmdb_id=1399 cho Game of Thrones). season_number=<integer>: Kết hợp với parent_tmdb_id (hoặc imdb_id của chương trình) để tìm phụ đề cho một mùa cụ thể. episode_number=<integer>: Kết hợp với parent_tmdb_id (hoặc imdb_id của chương trình) và season_number cho một tập cụ thể. languages=<string>: Lọc theo mã ngôn ngữ (phân cách bằng dấu phẩy, ví dụ: languages=en,es, languages=fr). Sử dụng mã ISO 639-2B (như eng, spa, fre). moviehash=<string>: Tìm kiếm bằng cách sử dụng một hash duy nhất được tính toán từ tệp video. Điều này cung cấp kết quả chính xác nhất nếu bạn có tệp video. Tính toán hash này thường yêu cầu các thư viện hoặc công cụ cụ thể. type=<string>: Lọc theo loại (movie hoặc episode). hearing_impaired=<include|exclude|only>: Lọc cho các phụ đề dành cho người khiếm thính. machine_translated=<include|exclude|only>: Lọc dựa trên việc phụ đề có phải được dịch bằng máy không. ai_translated=<include|exclude|only>: Lọc dựa trên việc phụ đề có được dịch bằng tính năng AI của API không. order_by=<field>: Sắp xếp kết quả (ví dụ: order_by=download_count). order_direction=<asc|desc>: Chỉ định hướng sắp xếp.
Ví dụ Yêu cầu Tìm kiếm (Tìm phụ đề tiếng Anh cho "Inception" qua ID TMDb):
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
Giải thích Kết quả Tìm kiếm:
Phản hồi là một đối tượng JSON chứa một mảng data. Mỗi phần tử trong mảng đại diện cho một kết quả phụ đề.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // ID Phụ đề (hữu ích nhưng không tải xuống)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // ID cũ
"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": "Đồng bộ và Sửa bởi ...",
"legacy_subtitle_id": 987654,
"uploader": {
"uploader_id": 54321,
"name": "UploaderName",
"rank": "Administrator"
},
"feature_details": { // Thông tin về phim/tập
"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": [
// ... liên kết đến nội dung liên quan ...
],
"files": [ // QUAN TRỌNG: Mảng này chứa tệp cho mục phụ đề này
{
"file_id": 998877, // <<< ĐÂY là ID cần cho điểm cuối /download
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Có thể có nhiều tệp hơn nếu đó là phụ đề nhiều phần (ví dụ, CD1, CD2)
]
}
},
// ... nhiều kết quả phụ đề hơn ...
]
}
Thông tin quan trọng nhất cần thiết để tải xuống là file_id được tìm thấy trong mảng attributes.files. Lưu ý rằng một mục phụ đề đơn (phần tử trong mảng data) có thể chứa nhiều tệp (ví dụ, cho các bản phát hành CD1/CD2 cũ hơn). Ứng dụng của bạn thường nên chọn file_id thích hợp dựa trên các tiêu chí như cd_number hoặc file_name.
Chức năng chính: Tải xuống phụ đề (/download)
Đến khi bạn đã xác định được tệp phụ đề mong muốn bằng cách sử dụng điểm cuối /subtitles và trích xuất file_id của nó, bạn có thể sử dụng điểm cuối /download để nhận một liên kết tạm thời đến tệp phụ đề thực tế.
Điểm cuối: POST /download
Mục đích: Để yêu cầu một liên kết tải xuống cho một tệp phụ đề cụ thể.
Xác thực: Yêu cầu tiêu đề Api-Key và xác thực người dùng hợp lệ (hoặc là một token JWT đăng nhập trong tiêu đề Authorization hoặc có thể là quyền cụ thể của Khóa API, tùy thuộc vào chính sách API – thường JWT được ưu tiên/cần thiết cho tải xuống để theo dõi hạn ngạch).
Nội dung yêu cầu:
{
"file_id": 998877 // file_id nhận được từ kết quả tìm kiếm
// Các tham số tùy chọn như "sub_format", "file_name", "in_fps", "out_fps" có thể có sẵn để chuyển đổi ngay lập tức
}
Tiêu đề:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Có thể yêu cầu) User-Agent: YourAppName v1.0
Phản hồi thành công (Ví dụ):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // URL tải xuống tạm thời
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Số yêu cầu còn lại cho liên kết/tệp cụ thể này? (Xem tài liệu)
"remaining": 95, // Hạn ngạch tải xuống còn lại của người dùng trong ngày/thời gian
"message": "Tải xuống thành công.",
"reset_time": "2023-10-27T12:00:00Z", // Khi hạn ngạch tải xuống có thể được đặt lại
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Quản lý tải xuống:
Thực hiện yêu cầu POST đến /download với file_id chính xác. Kiểm tra mã trạng thái phản hồi để xác nhận thành công (ví dụ: 200 OK). Trích xuất giá trị link từ phản hồi JSON. Thực hiện một yêu cầu HTTP GET tiêu chuẩn đến URL link này. Yêu cầu này không thường yêu cầu tiêu đề Khóa API hoặc xác thực, vì liên kết tự nó đã được xác thực trước. Phản hồi trong yêu cầu GET trên URL link sẽ là nội dung thực tế của tệp phụ đề (ví dụ: nội dung văn bản của tệp SRT). Lưu nội dung này vào một tệp (ví dụ: sử dụng file_name đã cho).
Quan trọng: Các liên kết tải xuống (link) thường là tạm thời và có thể hết hạn sau một khoảng thời gian ngắn hoặc sau một số lần sử dụng nhất định. Không lưu trữ các liên kết này để sử dụng lâu dài; hãy lấy một liên kết mới thông qua điểm cuối /download mỗi khi cần tải xuống. Cũng monitor số lượng tải xuống remaining để tránh làm cạn kiệt hạn ngạch của người dùng.
Tính năng nâng cao: Dịch AI (/ai-translation)
Một bổ sung gần đây cho công cụ OpenSubtitles là tính năng dịch tự động bằng AI.
Điểm cuối: POST /ai-translation (hoặc tương tự, kiểm tra điểm cuối chính xác trong tài liệu)
Mục đích: Để dịch một tệp phụ đề hiện có sang một ngôn ngữ khác bằng cách sử dụng các mô hình AI.
Cách thức hoạt động (Khái niệm):
Bạn có thể cung cấp file_id của phụ đề nguồn mà bạn muốn dịch. Bạn chỉ định target_language (ví dụ: target_language=de cho tiếng Đức). API xử lý yêu cầu, có thể thông báo trạng thái của công việc dịch. Phản hồi có thể chỉ ra trạng thái công việc hoặc cung cấp file_id mới hoặc liên kết tải xuống cho phụ đề đã dịch khi hoàn thành.
Trường hợp sử dụng:
Làm cho phụ đề khả dụng bằng các ngôn ngữ không có trong cơ sở dữ liệu ban đầu. Cung cấp tùy chọn dịch theo yêu cầu cho người dùng trong ứng dụng của bạn.
Cân nhắc:
Các dịch thuật AI có thể có chi phí hoặc tỷ lệ giới hạn/hạn ngạch cụ thể, có thể liên quan đến cấp VIP hoặc các cấp đăng ký. Chất lượng dịch thuật AI có thể thay đổi tùy thuộc vào cặp ngôn ngữ và độ phức tạp của văn bản nguồn. Tính năng này có thể yêu cầu quyền truy cập hoặc cấp độ đăng ký cụ thể của người dùng. Tham khảo tài liệu API để biết chi tiết về cách sử dụng, tham số và hạn chế.
Các thực hành tốt nhất cho tích hợp API
Để đảm bảo ứng dụng của bạn tương tác một cách mượt mà và có trách nhiệm với API OpenSubtitles, hãy làm theo các thực hành tốt nhất sau:
Cache phản hồi: Đặc biệt là với các kết quả tìm kiếm (/subtitles) không thay đổi nhanh chóng. Nếu người dùng tìm kiếm cùng một bộ phim/tập nhiều lần, hãy phục vụ kết quả cache thay vì tiếp tục gọi API. Triển khai cache thông minh với thời gian hết hạn hợp lý. Tôn trọng giới hạn tỷ lệ: Theo dõi tích cực các tiêu đề X-RateLimit-* và Retry-After. Triển khai các chiến lược tăng cường nếu bạn chạm đến giới hạn (chờ lâu hơn sau khi bị giới hạn tỷ lệ nhiều lần). Không truy vấn API một cách mạnh mẽ. Sử dụng các định danh cụ thể: Bất cứ khi nào có thể, hãy tìm kiếm bằng cách sử dụng imdb_id hoặc tmdb_id thay vì query. Những điều này cung cấp kết quả chính xác hơn nhiều và giảm thiểu sự mơ hồ. Sử dụng moviehash để có độ chính xác cao nhất nếu tệp video có sẵn. Cung cấp một User-Agent rõ ràng: Sử dụng một chuỗi User-Agent duy nhất và mô tả (ví dụ: MyMediaPlayerApp/2.1 (contact@myapp.com)). Điều này giúp OpenSubtitles xác định nguồn lưu lượng và khắc phục sự cố. Các agent chung có thể bị chặn. Quản lý lỗi một cách tinh tế: Kiểm tra mã trạng thái HTTP cho mỗi phản hồi. Triển khai logic để xử lý các lỗi thông thường như 401 Unauthorized (Khóa API/JWT không hợp lệ), 403 Forbidden (quyền bị từ chối), 404 Not Found, 429 Too Many Requests, và 5xx lỗi máy chủ. Cung cấp phản hồi thông tin cho người dùng. Quản lý hạn ngạch tải xuống: Hãy chú ý đến các giới hạn tải xuống hàng ngày/thời gian gắn liền với tài khoản của người dùng (hoặc Khóa API). Thông báo cho người dùng nếu họ đang gần hoặc đã vượt quá hạn ngạch của mình. Sử dụng trường remaining trong phản hồi /download. Tối ưu hóa tìm kiếm: Đừng yêu cầu dữ liệu không cần thiết. Sử dụng các tham số như languages, type, hearing_impaired v.v. để thu hẹp kết quả máy chủ thay vì lọc các tập dữ liệu lớn phía client. Bảo mật Khóa API của bạn: Đối xử với Khóa API của bạn như một mật khẩu. Không nhúng nó trực tiếp vào mã phía client. Bảo mật nó trên máy chủ của bạn.
Các trình bao bọc, tập lệnh và Tài nguyên Cộng đồng
Trong khi hướng dẫn này đề cập đến tương tác API trực tiếp, sinh thái OpenSubtitles thường bao gồm các tài nguyên do cộng đồng phát triển.
API Wrappers: Tìm kiếm các thư viện hoặc SDK cho ngôn ngữ lập trình của bạn (ví dụ: Python, JavaScript, Java) trên các nền tảng như GitHub hoặc các trình quản lý gói (PyPI, npm). Những wrappers này có thể đơn giản hóa các gọi API, xử lý xác thực và phân tích phản hồi. Tập lệnh: Nhiều công cụ dòng lệnh hoặc tập lệnh có thể tồn tại để tương tác với API, hữu ích cho tự động hóa hoặc tìm kiếm nhanh. Diễn đàn/Cộng đồng: Kiểm tra các diễn đàn OpenSubtitles hoặc các cộng đồng nhà phát triển liên quan để thảo luận, ví dụ và các công cụ bên thứ ba có thể sử dụng API.
Sử dụng một wrapper được duy trì tốt có thể làm tăng tốc độ phát triển đáng kể, nhưng hiểu các gọi API cơ bản (như mô tả trong hướng dẫn này) vẫn là quan trọng đối với việc khắc phục sự cố và sử dụng nâng cao.
Đăng ký và Giá vào API
OpenSubtitles thường cung cấp các mức độ truy cập khác nhau đến API của mình:
Miễn phí: Thông thường cung cấp quyền truy cập cơ bản với các giới hạn tỷ lệ và hạn ngạch tải xuống nghiêm ngặt hơn. Phù hợp cho các ứng dụng có lưu lượng thấp hoặc phát triển/thực hiện thử nghiệm. Các cấp VIP/Trả phí: Cung cấp giới hạn tỷ lệ cao hơn nhiều, hạn ngạch tải xuống lớn hơn, truy cập vào các tính năng cao cấp (như có thể là Dịch AI hoặc hỗ trợ nhanh hơn), và dành cho các ứng dụng thương mại hoặc có lưu lượng lớn.
Tham khảo tài liệu API OpenSubtitles chính thức hoặc trang web để biết thông tin chi tiết nhất về các kế hoạch đăng ký, giá cả và các giới hạn/tính năng cụ thể đi kèm với từng cấp. Chọn kế hoạch phù hợp nhất với việc sử dụng và yêu cầu tính năng dự kiến của ứng dụng của bạn.
Kết luận
API OpenSubtitles là một cánh cửa mạnh mẽ đến một trong những bộ sưu tập phụ đề lớn nhất thế giới. Bằng cách hiểu cấu trúc của nó, các phương pháp xác thực, các điểm cuối chính như /subtitles và /download, và tuân thủ các thực hành tốt nhất, các lập trình viên có thể tích hợp chức năng phụ đề một cách mượt mà vào ứng dụng của họ. Từ việc tìm kiếm đơn giản trong các trình phát media đến các tính năng phức tạp liên quan đến dịch AI, API cung cấp các khối xây dựng cho những trải nghiệm sáng tạo và thân thiện với người dùng. Hãy nhớ tham khảo tài liệu API OpenSubtitles chính thức để biết thông tin chi tiết về các điểm cuối, tham số và quy định cập nhật nhất khi bạn bắt đầu hành trình phát triển của mình. Chúc bạn lập trình vui vẻ!