Subtitel adalah bagian tak terpisahkan dari pengalaman media modern. Mereka menjembatani hambatan bahasa, meningkatkan aksesibilitas bagi tunarungu, dan membantu pelajar bahasa di seluruh dunia. Inti dari aksesibilitas subtitel terletak pada OpenSubtitles, salah satu repositori online terbesar dan terpopuler untuk file subtitel. Tetapi OpenSubtitles lebih dari sekadar situs web; ia menawarkan REST API yang kuat yang memungkinkan pengembang untuk mengintegrasikan basis data subtitelnya yang luas langsung ke dalam aplikasi mereka.
Baik Anda sedang membangun pemutar media, sistem manajemen konten, alat pembelajaran bahasa, atau aplikasi apa pun yang dapat memanfaatkan integrasi subtitel, OpenSubtitles API menyediakan alat yang diperlukan. Panduan komprehensif ini akan memandu Anda melalui semua yang perlu Anda ketahui untuk memanfaatkan OpenSubtitles API secara efektif, mulai dari pengaturan awal dan autentikasi hingga mencari, mengunduh, menerjemahkan subtitel, dan mematuhi praktik terbaik.
Ingin platform All-in-One terintegrasi bagi Tim Pengembang Anda untuk bekerja bersama dengan produktivitas maksimum?
Apidog memberikan semua permintaan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
Apa itu OpenSubtitles API?
OpenSubtitles API adalah serangkaian antarmuka pemrograman yang memungkinkan pengembang untuk berinteraksi secara terprogram dengan basis data OpenSubtitles. Alih-alih mencari dan mengunduh subtitel secara manual dari situs web, aplikasi dapat menggunakan API untuk melakukan tindakan ini secara otomatis. Ini membuka dunia kemungkinan untuk menciptakan pengalaman pengguna yang mulus dan kaya fitur.
Kemampuan Utama:
Pencarian: Temukan subtitel berdasarkan berbagai kriteria seperti judul film/acara, IMDB ID, TMDB ID, hash file, bahasa, dan lainnya. Unduh: Ambil file subtitel tertentu yang diidentifikasi melalui hasil pencarian. Terjemahan AI: Manfaatkan kecerdasan buatan untuk menerjemahkan subtitel yang ada ke dalam bahasa yang berbeda. Pengambilan Informasi: Akses metadata tentang subtitel dan media.
Memulai: Langkah Pertama Anda
Sebelum Anda dapat melakukan panggilan ke API, ada beberapa prasyarat dan konsep dasar yang perlu dipahami.
1. Endpoint API:
Semua interaksi dengan OpenSubtitles REST API terjadi melalui satu URL dasar:
https://api.opensubtitles.com/api/v1
Semua endpoint spesifik (seperti mencari atau mengunduh) ditambahkan ke URL dasar ini.
2. Pendaftaran dan API Key:
Mengakses API memerlukan autentikasi. Metode utama melibatkan penggunaan API Key.
Daftar: Anda pertama-tama memerlukan akun di OpenSubtitles. Jika Anda belum memilikinya, daftar di situs web mereka. Dapatkan API Key: Setelah terdaftar, Anda perlu membuat API Key. Ini biasanya dilakukan melalui profil pengguna Anda atau bagian pengembang khusus di situs web OpenSubtitles. Jaga keamanan API Key Anda, karena ini mengidentifikasi permintaan aplikasi Anda.
3. Autentikasi:
API mendukung dua metode autentikasi utama:
API Key: Metode paling sederhana. Sertakan API Key Anda di header Api-Key dari setiap permintaan. Api-Key: API_KEY_ANDA JWT Token: Untuk berpotensi mengakses lebih banyak fitur khusus pengguna atau batas laju yang berbeda (tergantung pada desain API), Anda dapat masuk melalui endpoint /login (dibahas nanti) untuk mendapatkan JSON Web Token (JWT). Token ini kemudian disertakan dalam header Authorization sebagai token Bearer. Authorization: Bearer JWT_TOKEN_ANDA
Anda masih umumnya perlu memberikan header Api-Key bahkan saat menggunakan token JWT untuk identifikasi aplikasi.
4. Header Penting:
Selain header autentikasi, setiap permintaan API harus menyertakan:
Content-Type: Untuk permintaan dengan body (seperti permintaan POST), ini biasanya harus application/json. Content-Type: application/json **User-Agent:** Ini sangat penting. API memerlukan string User-Agent deskriptif yang mengidentifikasi aplikasi Anda. User-Agent yang tidak jelas atau default (seperti python-requests) mungkin diblokir. Format yang baik adalah NamaAplikasiAnda v1.0. User-Agent: AplikasiSubtitelSaya v1.2.3
5. Pembatasan Laju:
Seperti kebanyakan API publik, OpenSubtitles memberlakukan pembatasan laju untuk memastikan penggunaan yang adil dan stabilitas server. Melebihi batas ini akan menghasilkan respons kesalahan (seringkali 429 Too Many Requests). Perhatikan baik-baik header respons berikut untuk mengelola laju permintaan Anda:
X-RateLimit-Limit: Jumlah maksimum permintaan yang diizinkan di jendela saat ini. X-RateLimit-Remaining: Jumlah permintaan yang tersisa di jendela saat ini. X-RateLimit-Reset: Stempel waktu (seringkali waktu epoch Unix) saat jendela batas laju direset. Retry-After: Jika Anda menerima kesalahan 429, header ini menunjukkan berapa detik Anda harus menunggu sebelum mencoba lagi.
Menerapkan logika dalam aplikasi Anda untuk menghormati header ini sangat penting untuk operasi yang andal.
Pendalaman Autentikasi: Endpoint /login
Meskipun hanya menggunakan API Key seringkali sudah cukup, endpoint /login memungkinkan aplikasi Anda untuk mengautentikasi sebagai pengguna OpenSubtitles tertentu, mendapatkan JWT.
Endpoint: POST /login
Tujuan: Untuk menukar kredensial pengguna (nama pengguna/kata sandi) dengan token autentikasi JWT.
Request Body:
{
"username": "nama_pengguna_opensubtitles_anda",
"password": "kata_sandi_opensubtitles_anda"
}
Header:
Content-Type: application/jsonAccept: application/jsonApi-Key: API_KEY_ANDAUser-Agent: NamaAplikasiAnda v1.0
Respons Berhasil (Contoh):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Ini adalah JWT
"status": 200
}
Menggunakan JWT:
Setelah diperoleh, sertakan nilai token ini di header Authorization untuk permintaan berikutnya:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Menggunakan JWT dapat memberikan akses ke kuota unduhan khusus pengguna atau fitur lain yang terkait dengan tingkat akun atau status VIP pengguna. Ingatlah bahwa JWT biasanya memiliki waktu kedaluwarsa, jadi Anda mungkin perlu mengautentikasi ulang secara berkala.
Fungsi Inti: Mencari Subtitel (/subtitles)
Ini mungkin endpoint yang paling sering digunakan. Ini memungkinkan Anda untuk menanyakan basis data OpenSubtitles yang luas.
Endpoint: GET /subtitles
Tujuan: Untuk menemukan subtitel berdasarkan berbagai kriteria pencarian.
Autentikasi: Memerlukan header Api-Key (dan opsional Authorization: Bearer <token>).
Parameter Kueri Utama:
Kekuatan pencarian terletak pada parameter kuerinya yang fleksibel. Anda dapat menggabungkan ini sesuai kebutuhan:
query=<string>: Cari berdasarkan judul film atau episode (mis., query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: Cari menggunakan IMDb ID (mis., imdb_id=tt0133093). Ini seringkali lebih akurat daripada query. tmdb_id=<integer>: Cari menggunakan The Movie Database (TMDb) ID (mis., tmdb_id=603). Juga sangat akurat. parent_tmdb_id=<integer>: Untuk mencari episode, gunakan TMDb ID dari acara (mis., parent_tmdb_id=1399 untuk Game of Thrones). season_number=<integer>: Gabungkan dengan parent_tmdb_id (atau imdb_id dari acara) untuk menemukan subtitel untuk musim tertentu. episode_number=<integer>: Gabungkan dengan parent_tmdb_id (atau imdb_id dari acara) dan season_number untuk episode tertentu. languages=<string>: Filter berdasarkan kode bahasa (dipisahkan koma, mis., languages=en,es, languages=fr). Gunakan kode ISO 639-2B (seperti eng, spa, fre). moviehash=<string>: Cari menggunakan hash unik yang dihitung dari file video. Ini memberikan kecocokan paling akurat jika Anda memiliki file video itu sendiri. Menghitung hash ini biasanya memerlukan pustaka atau alat tertentu. type=<string>: Filter berdasarkan jenis (movie atau episode). hearing_impaired=<include|exclude|only>: Filter untuk subtitel yang dirancang untuk tunarungu. machine_translated=<include|exclude|only>: Filter berdasarkan apakah subtitel diterjemahkan oleh mesin. ai_translated=<include|exclude|only>: Filter berdasarkan apakah subtitel diterjemahkan menggunakan fitur AI API. order_by=<field>: Urutkan hasil (mis., order_by=download_count). order_direction=<asc|desc>: Tentukan arah pengurutan.
Contoh Permintaan Pencarian (Menemukan subtitel bahasa Inggris untuk "Inception" melalui TMDb ID):
GET /api/v1/subtitles?tmdb_id=27205&languages=en HTTP/1.1
Host: api.opensubtitles.com
Api-Key: API_KEY_ANDA
User-Agent: AplikasiSubtitelSaya v1.0
Accept: application/json
Menafsirkan Hasil Pencarian:
Responsnya adalah objek JSON yang berisi array data. Setiap elemen dalam array mewakili kecocokan subtitel.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // Subtitle ID (berguna tetapi tidak untuk diunduh)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // ID Warisan
"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": "Disinkronkan dan Dikoreksi oleh ...",
"legacy_subtitle_id": 987654,
"uploader": {
"uploader_id": 54321,
"name": "NamaPengunggah",
"rank": "Administrator"
},
"feature_details": { // Informasi tentang film/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": [
// ... tautan ke konten terkait ...
],
"files": [ // PENTING: Array ini berisi file untuk entri subtitel ini
{
"file_id": 998877, // <<< INI adalah ID yang diperlukan untuk endpoint /download
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Berpotensi lebih banyak file jika ini adalah subtitel multi-bagian (mis., CD1, CD2)
]
}
},
// ... lebih banyak hasil subtitel ...
]
}
Informasi terpenting yang diperlukan untuk mengunduh adalah file_id yang ditemukan di dalam array attributes.files. Perhatikan bahwa satu entri subtitel (elemen array data) mungkin berisi beberapa file (mis., untuk rilis CD1/CD2 yang lebih lama). Aplikasi Anda biasanya harus memilih file_id yang sesuai berdasarkan kriteria seperti cd_number atau file_name.
Fungsi Inti: Mengunduh Subtitel (/download)
Setelah Anda mengidentifikasi file subtitel yang diinginkan menggunakan endpoint /subtitles dan mengekstrak file_id-nya, Anda dapat menggunakan endpoint /download untuk mendapatkan tautan sementara ke file subtitel yang sebenarnya.
Endpoint: POST /download
Tujuan: Untuk meminta tautan unduhan untuk file subtitel tertentu.
Autentikasi: Memerlukan header Api-Key dan autentikasi pengguna yang valid (baik token JWT yang masuk di header Authorization atau berpotensi izin API key tertentu, tergantung pada kebijakan API – seringkali JWT lebih disukai/diperlukan untuk unduhan untuk melacak kuota).
Request Body:
{
"file_id": 998877 // File_id yang diperoleh dari hasil pencarian
// Parameter opsional seperti "sub_format", "file_name", "in_fps", "out_fps" mungkin tersedia untuk konversi langsung
}
Header:
Content-Type: application/jsonAccept: application/jsonApi-Key: API_KEY_ANDAAuthorization: Bearer JWT_TOKEN_ANDA (Kemungkinan diperlukan) User-Agent: NamaAplikasiAnda v1.0
Respons Berhasil (Contoh):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // URL unduhan sementara
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Jumlah permintaan yang tersedia untuk tautan/file spesifik ini? (Periksa dokumen)
"remaining": 95, // Kuota unduhan pengguna yang tersisa untuk hari/periode tersebut
"message": "Jumlah unduhan berhasil.",
"reset_time": "2023-10-27T12:00:00Z", // Kapan kuota unduhan mungkin direset
"reset_time_utc": "2023-10-27T12:00:00Z"
}
Menangani Unduhan:
Buat permintaan POST ke /download dengan file_id yang benar. Periksa kode status respons untuk keberhasilan (mis., 200 OK). Ekstrak nilai link dari respons JSON. Buat permintaan HTTP GET standar ke URL link ini. Permintaan ini tidak biasanya memerlukan API Key atau header Authorization, karena tautan itu sendiri telah diotorisasi sebelumnya. Respons terhadap permintaan GET pada URL link akan menjadi konten file subtitel yang sebenarnya (mis., teks file SRT). Simpan konten ini ke file (mis., menggunakan file_name yang disediakan).
Penting: Tautan unduhan (link) biasanya bersifat sementara dan dapat kedaluwarsa setelah jangka waktu singkat atau sejumlah penggunaan tertentu. Jangan menyimpan tautan ini untuk penggunaan jangka panjang; ambil tautan baru melalui endpoint /download setiap kali unduhan diperlukan. Juga, pantau jumlah unduhan remaining untuk menghindari menghabiskan kuota pengguna.
Fitur Lanjutan: Terjemahan AI (/ai-translation)
Tambahan yang lebih baru untuk toolkit OpenSubtitles adalah fitur terjemahan bertenaga AI.
Endpoint: POST /ai-translation (atau serupa, periksa endpoint yang tepat di dokumen)
Tujuan: Untuk menerjemahkan file subtitel yang ada ke bahasa lain menggunakan model AI.
Cara Kerjanya (Konseptual):
Anda mungkin memberikan file_id dari subtitel sumber yang ingin Anda terjemahkan. Anda menentukan target_language (mis., target_language=de untuk bahasa Jerman). API memproses permintaan, berpotensi mengantrekan pekerjaan terjemahan. Respons mungkin menunjukkan status pekerjaan atau memberikan file_id atau tautan unduhan baru untuk subtitel yang diterjemahkan setelah selesai.
Kasus Penggunaan:
Membuat subtitel tersedia dalam bahasa yang awalnya tidak ada dalam basis data. Memberikan pengguna opsi terjemahan sesuai permintaan di dalam aplikasi Anda.
Pertimbangan:
Terjemahan AI mungkin memiliki biaya terkait atau batas laju/kuota tertentu, berpotensi terkait dengan tingkat VIP atau langganan. Kualitas terjemahan AI dapat bervariasi tergantung pada pasangan bahasa dan kompleksitas teks sumber. Fitur ini mungkin memerlukan izin pengguna atau tingkat langganan tertentu. Konsultasikan dokumentasi API untuk detail tentang penggunaan, parameter, dan batasan.
Praktik Terbaik untuk Integrasi API
Untuk memastikan aplikasi Anda berinteraksi dengan lancar dan bertanggung jawab dengan OpenSubtitles API, ikuti praktik terbaik ini:
Cache Respons: Terutama untuk hasil pencarian (/subtitles) yang tidak berubah dengan cepat. Jika pengguna mencari film/episode yang sama beberapa kali, sajikan hasil yang di-cache alih-alih memukul API berulang kali. Terapkan caching cerdas dengan waktu kedaluwarsa yang wajar. Hormati Batas Laju: Pantau secara aktif header X-RateLimit-* dan Retry-After. Terapkan strategi backoff eksponensial jika Anda mencapai batas (tunggu lebih lama setelah pembatasan laju berulang). Jangan melakukan polling API secara agresif. Gunakan Pengidentifikasi Spesifik: Sebisa mungkin, cari menggunakan imdb_id atau tmdb_id alih-alih query. Ini memberikan hasil yang jauh lebih akurat dan mengurangi ambiguitas. Gunakan moviehash untuk akurasi tertinggi jika file video tersedia. Berikan User-Agent yang Jelas: Gunakan string User-Agent yang unik dan deskriptif (mis., MyMediaPlayerApp/2.1 (contact@myapp.com)). Ini membantu OpenSubtitles mengidentifikasi sumber lalu lintas dan memecahkan masalah. Agen generik mungkin diblokir. Tangani Kesalahan dengan Anggun: Periksa kode status HTTP untuk setiap respons. Terapkan logika untuk menangani kesalahan umum seperti 401 Unauthorized (API Key/JWT tidak valid), 403 Forbidden (izin ditolak), 404 Not Found, 429 Too Many Requests, dan kesalahan server 5xx. Berikan umpan balik informatif kepada pengguna. Kelola Kuota Unduhan: Perhatikan batas unduhan harian/berkala yang terkait dengan akun pengguna (atau API key). Beri tahu pengguna jika mereka mendekati atau telah melampaui kuota mereka. Gunakan bidang remaining dalam respons /download. Optimalkan Pencarian: Jangan meminta data yang tidak perlu. Gunakan parameter seperti languages, type, hearing_impaired dll., untuk mempersempit hasil di sisi server daripada memfilter dataset besar di sisi klien. Amankan API Key Anda: Perlakukan API Key Anda seperti kata sandi. Jangan menyematkannya langsung dalam kode sisi klien. Simpan dengan aman di server Anda.
Wrapper, Skrip, dan Sumber Daya Komunitas
Meskipun panduan ini mencakup interaksi API langsung, ekosistem OpenSubtitles sering kali menyertakan sumber daya yang dikembangkan oleh komunitas.
API Wrapper: Cari pustaka atau SDK untuk bahasa pemrograman Anda (mis., Python, JavaScript, Java) di platform seperti GitHub atau pengelola paket (PyPI, npm). Wrapper ini dapat menyederhanakan panggilan API, menangani autentikasi, dan mengurai respons. Skrip: Berbagai alat atau skrip baris perintah mungkin ada untuk berinteraksi dengan API, berguna untuk otomatisasi atau pencarian cepat. Forum/Komunitas: Periksa forum OpenSubtitles atau komunitas pengembang terkait untuk diskusi, contoh, dan potensi alat pihak ketiga yang memanfaatkan API.
Menggunakan wrapper yang dipelihara dengan baik dapat secara signifikan mempercepat pengembangan, tetapi memahami panggilan API yang mendasarinya (seperti yang dijelaskan dalam panduan ini) tetap penting untuk pemecahan masalah dan penggunaan tingkat lanjut.
Langganan dan Harga API
OpenSubtitles biasanya menawarkan tingkat akses yang berbeda ke API-nya:
Tingkat Gratis: Biasanya menyediakan akses dasar dengan batas laju dan kuota unduhan yang lebih ketat. Cocok untuk aplikasi volume rendah atau pengembangan/pengujian. Tingkat VIP/Berbayar: Menawarkan batas laju yang jauh lebih tinggi, kuota unduhan yang lebih besar, akses ke fitur premium (seperti berpotensi Terjemahan AI atau dukungan yang lebih cepat), dan ditujukan untuk aplikasi komersial atau lalu lintas tinggi.
Lihat dokumentasi atau situs web OpenSubtitles API resmi untuk detail terbaru tentang paket berlangganan, harga, dan batas/fitur spesifik yang terkait dengan setiap tingkat. Pilih paket yang paling sesuai dengan perkiraan penggunaan dan persyaratan fitur aplikasi Anda.
Kesimpulan
OpenSubtitles API adalah pintu gerbang yang kuat ke salah satu koleksi subtitel terbesar di dunia. Dengan memahami strukturnya, metode autentikasi, endpoint inti seperti /subtitles dan /download, dan mematuhi praktik terbaik, pengembang dapat dengan mulus mengintegrasikan fungsionalitas subtitel ke dalam aplikasi mereka. Dari pencarian sederhana di pemutar media hingga fitur kompleks yang melibatkan terjemahan AI, API menyediakan blok bangunan untuk pengalaman inovatif dan ramah pengguna. Ingatlah untuk berkonsultasi dengan dokumentasi OpenSubtitles API resmi untuk detail endpoint, parameter, dan kebijakan terbaru saat Anda memulai perjalanan pengembangan Anda. Selamat membuat kode!
