Altyazılar, modern medya deneyiminin vazgeçilmez bir parçasıdır. Dil engellerini aşar, işitme engelliler için erişilebilirliği artırır ve dünya çapında dil öğrenenlere yardımcı olur. Altyazı erişilebilirliğinin kalbinde, en büyük ve en popüler çevrimiçi altyazı dosyası depolarından biri olan OpenSubtitles yer alır. Ancak OpenSubtitles sadece bir web sitesinden daha fazlasıdır; geliştiricilerin geniş altyazı veritabanını doğrudan uygulamalarına entegre etmelerini sağlayan güçlü bir REST API sunar.
İster bir medya oynatıcı, ister bir içerik yönetim sistemi, ister bir dil öğrenme aracı veya altyazı entegrasyonundan yararlanabilecek herhangi bir uygulama geliştiriyor olun, OpenSubtitles API gerekli araçları sağlar. Bu kapsamlı kılavuz, ilk kurulum ve kimlik doğrulamasından aramaya, indirmeye, altyazıları çevirmeye ve en iyi uygulamalara uymaya kadar OpenSubtitles API'sini etkili bir şekilde kullanmak için bilmeniz gereken her şeyi size adım adım anlatacaktır.
Geliştirici Ekibinizin maksimum verimlilikle birlikte çalışması için entegre, Hepsi Bir Arada bir platform mu istiyorsunuz?
Apidog tüm taleplerinizi karşılar ve Postman'in yerini çok daha uygun bir fiyata alır!
OpenSubtitles API Nedir?
OpenSubtitles API, geliştiricilerin OpenSubtitles veritabanıyla programlı olarak etkileşim kurmasını sağlayan bir dizi programlama arabirimidir. Web sitesinden altyazıları manuel olarak aramak ve indirmek yerine, uygulamalar bu eylemleri otomatik olarak gerçekleştirmek için API'yi kullanabilir. Bu, kusursuz ve özellik açısından zengin kullanıcı deneyimleri oluşturmak için bir olasılıklar dünyasının kapılarını açar.
Temel Yetenekler:
Arama: Film/dizi başlığı, IMDB ID'si, TMDB ID'si, dosya karması, dil ve daha fazlası gibi çeşitli kriterlere göre altyazı bulun. İndirme: Arama sonuçları aracılığıyla tanımlanan belirli altyazı dosyalarını alın. AI Çevirisi: Mevcut altyazıları farklı dillere çevirmek için yapay zekadan yararlanın. Bilgi Alma: Altyazılar ve medya hakkında meta verilere erişin.
Başlarken: İlk Adımlarınız
API'ye çağrı yapabilmeniz için, anlaşılması gereken birkaç ön koşul ve temel kavram vardır.
1. API Uç Noktası:
OpenSubtitles REST API ile yapılan tüm etkileşimler tek bir temel URL üzerinden gerçekleşir:
https://api.opensubtitles.com/api/v1
Tüm belirli uç noktalar (arama veya indirme gibi) bu temel URL'ye eklenir.
2. Kayıt ve API Anahtarı:
API'ye erişim kimlik doğrulaması gerektirir. Birincil yöntem, bir API Anahtarı kullanmayı içerir.
Kaydol: İlk olarak OpenSubtitles'ta bir hesaba ihtiyacınız var. Eğer yoksa, web sitelerine kaydolun. API Anahtarı Alın: Kaydolduktan sonra, bir API Anahtarı oluşturmanız gerekecektir. Bu genellikle kullanıcı profiliniz veya OpenSubtitles web sitesindeki özel bir geliştirici bölümü aracılığıyla yapılır. API Anahtarınızı güvenli bir şekilde saklayın, çünkü uygulamanızın isteklerini tanımlar.
3. Kimlik Doğrulama:
API iki ana kimlik doğrulama yöntemini destekler:
API Anahtarı: En basit yöntem. API Anahtarınızı her isteğin Api-Key başlığına ekleyin. Api-Key: YOUR_API_KEY JWT Token: Daha fazla kullanıcıya özel özelliklere veya farklı hız sınırlamalarına erişmek için (API tasarımına bağlı olarak), bir JSON Web Token (JWT) elde etmek için /login uç noktasından (daha sonra ele alınacaktır) oturum açabilirsiniz. Bu token daha sonra Authorization başlığına Taşıyıcı token olarak eklenir. Authorization: Bearer YOUR_JWT_TOKEN
Uygulama kimliği için bir JWT token kullanırken bile genellikle Api-Key başlığını sağlamanız gerekir.
4. Temel Başlıklar:
Kimlik doğrulama başlıklarının yanı sıra, her API isteği şunları içermelidir:
Content-Type: Bir gövdesi olan istekler için (POST istekleri gibi), bu genellikle application/json olmalıdır. Content-Type: application/json **User-Agent:** Bu çok önemlidir. API, uygulamanızı tanımlayan açıklayıcı bir User-Agent dizesi gerektirir. Belirsiz veya varsayılan User-Agent'lar (python-requests gibi) engellenebilir. İyi bir format YourAppName v1.0'dır. User-Agent: MySubtitleApp v1.2.3
5. Hız Sınırlaması:
Çoğu genel API gibi, OpenSubtitles da adil kullanım ve sunucu kararlılığını sağlamak için hız sınırları uygular. Bu sınırların aşılması hata yanıtlarına neden olacaktır (genellikle 429 Too Many Requests). İstek hızınızı yönetmek için aşağıdaki yanıt başlıklarına çok dikkat edin:
X-RateLimit-Limit: Geçerli pencerede izin verilen maksimum istek sayısı. X-RateLimit-Remaining: Geçerli pencerede kalan istek sayısı. X-RateLimit-Reset: Hız sınırı penceresinin sıfırlandığı zaman damgası (genellikle Unix epoch zamanı). Retry-After: 429 hatası alırsanız, bu başlık kaç saniye sonra tekrar denemeniz gerektiğini gösterir.
Uygulamanızda bu başlıkları dikkate almak için mantık uygulamak, güvenilir çalışma için çok önemlidir.
Kimlik Doğrulama Derinlemesine İnceleme: /login Uç Noktası
Sadece API Anahtarını kullanmak genellikle yeterli olsa da, /login uç noktası uygulamanızın belirli bir OpenSubtitles kullanıcısı olarak kimlik doğrulaması yapmasını ve bir JWT elde etmesini sağlar.
Uç Nokta: POST /login
Amaç: Kullanıcı kimlik bilgilerini (kullanıcı adı/şifre) bir JWT kimlik doğrulama tokeni ile değiştirmek.
İstek Gövdesi:
{
"username": "your_opensubtitles_username",
"password": "your_opensubtitles_password"
}
Başlıklar:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYUser-Agent: YourAppName v1.0
Başarılı Yanıt (Örnek):
{
"user": {
"allowed_downloads": 100,
"level": "Sub leecher",
"user_id": 123456,
"ext_installed": false,
"vip": false
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Bu JWT'dir
"status": 200
}
JWT'yi Kullanma:
Elde edildikten sonra, bu token değerini sonraki istekler için Authorization başlığına ekleyin:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
JWT kullanmak, kullanıcının hesabının seviyesine veya VIP durumuna bağlı olarak kullanıcıya özel indirme kotalarına veya diğer özelliklere erişim sağlayabilir. JWT'lerin genellikle bir son kullanma süresi olduğunu unutmayın, bu nedenle periyodik olarak yeniden kimlik doğrulama yapmanız gerekebilir.
Temel İşlevsellik: Altyazı Arama (/subtitles)
Bu, belki de en sık kullanılan uç noktadır. Geniş OpenSubtitles veritabanını sorgulamanıza olanak tanır.
Uç Nokta: GET /subtitles
Amaç: Çeşitli arama kriterlerine göre altyazı bulmak.
Kimlik Doğrulama: Api-Key başlığı (ve isteğe bağlı olarak Authorization: Bearer <token>) gerektirir.
Temel Sorgu Parametreleri:
Aramanın gücü, esnek sorgu parametrelerinde yatar. Bunları gerektiği gibi birleştirebilirsiniz:
query=<string>: Film veya bölüm adına göre arama yapın (örneğin, query=The Matrix, query=Game of Thrones S01E01). imdb_id=<string>: IMDb ID'sini kullanarak arama yapın (örneğin, imdb_id=tt0133093). Bu genellikle query'den daha doğrudur. tmdb_id=<integer>: The Movie Database (TMDb) ID'sini kullanarak arama yapın (örneğin, tmdb_id=603). Ayrıca çok doğru. parent_tmdb_id=<integer>: Bölümleri aramak için, dizinin TMDb ID'sini kullanın (örneğin, Game of Thrones için parent_tmdb_id=1399). season_number=<integer>: Belirli bir sezon için altyazı bulmak için parent_tmdb_id (veya dizinin imdb_id'si) ile birleştirin. episode_number=<integer>: Belirli bir bölüm için parent_tmdb_id (veya dizinin imdb_id'si) ve season_number ile birleştirin. languages=<string>: Dil kodlarına göre filtreleyin (virgülle ayrılmış, örneğin, languages=en,es, languages=fr). ISO 639-2B kodlarını kullanın (eng, spa, fre gibi). moviehash=<string>: Video dosyasından hesaplanan benzersiz bir karma kullanarak arama yapın. Bu, video dosyasının kendiniz varsa en doğru eşleşmeyi sağlar. Bu karmayı hesaplamak genellikle belirli kitaplıklar veya araçlar gerektirir. type=<string>: Türe göre filtreleyin (movie veya episode). hearing_impaired=<include|exclude|only>: İşitme engelliler için tasarlanmış altyazıları filtreleyin. machine_translated=<include|exclude|only>: Altyazıların makine tarafından çevrilip çevrilmediğine göre filtreleyin. ai_translated=<include|exclude|only>: Altyazıların API'nin AI özelliği kullanılarak çevrilip çevrilmediğine göre filtreleyin. order_by=<field>: Sonuçları sıralayın (örneğin, order_by=download_count). order_direction=<asc|desc>: Sıralama yönünü belirtin.
Örnek Arama İsteği ("Inception" için İngilizce altyazı bulma, TMDb ID'si aracılığıyla):
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
Arama Sonuçlarını Yorumlama:
Yanıt, bir data dizisi içeren bir JSON nesnesidir. Dizideki her öğe bir altyazı eşleşmesini temsil eder.
{
"total_pages": 10,
"total_count": 195,
"per_page": 20,
"page": 1,
"data": [
{
"id": "1234567", // Altyazı Kimliği (kullanışlı ancak indirme için değil)
"type": "subtitles",
"attributes": {
"subtitle_id": "1234567", // Eski Kimlik
"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": { // Film/bölüm hakkında bilgiler
"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": [
// ... ilgili içeriğe bağlantılar ...
],
"files": [ // ÖNEMLİ: Bu dizi, bu altyazı girişi için dosyayı/dosyaları içerir
{
"file_id": 998877, // <<< /download uç noktası için GEREKLİ olan BU Kimlik
"cd_number": 1,
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt"
}
// Çok parçalı bir altyazıysa (örneğin, CD1, CD2) potansiyel olarak daha fazla dosya
]
}
},
// ... daha fazla altyazı sonucu ...
]
}
İndirme için gereken en önemli bilgi, attributes.files dizisinde bulunan file_id'dir. Tek bir altyazı girişinin (data dizi öğesi) birden fazla dosya içerebileceğini (örneğin, eski CD1/CD2 sürümleri için) unutmayın. Uygulamanız genellikle cd_number veya file_name gibi kriterlere göre uygun file_id'yi seçmelidir.
Temel İşlevsellik: Altyazı İndirme (/download)
/subtitles uç noktasını kullanarak istenen altyazı dosyasını belirledikten ve file_id'sini çıkardıktan sonra, gerçek altyazı dosyasına geçici bir bağlantı almak için /download uç noktasını kullanabilirsiniz.
Uç Nokta: POST /download
Amaç: Belirli bir altyazı dosyası için bir indirme bağlantısı talep etmek.
Kimlik Doğrulama: Api-Key başlığı ve geçerli kullanıcı kimlik doğrulaması (Authorization başlığında oturum açmış bir JWT tokeni veya API politikasına bağlı olarak potansiyel olarak belirli API anahtarı izinleri - genellikle indirmeler için JWT tercih edilir/gerekir) gerektirir.
İstek Gövdesi:
{
"file_id": 998877 // Arama sonuçlarından elde edilen file_id
// "sub_format", "file_name", "in_fps", "out_fps" gibi isteğe bağlı parametreler anında dönüştürme için kullanılabilir
}
Başlıklar:
Content-Type: application/jsonAccept: application/jsonApi-Key: YOUR_API_KEYAuthorization: Bearer YOUR_JWT_TOKEN (Muhtemelen gerekli) User-Agent: YourAppName v1.0
Başarılı Yanıt (Örnek):
{
"link": "<https://dl.opensubtitles.org/en/download/sub/1234567?uk=USER_KEY&uuid=RANDOM_UUID&filename=>...", // Geçici indirme URL'si
"file_name": "Inception.2010.720p.BluRay.x264-REWARD.srt",
"requests": 5, // Bu belirli bağlantı/dosya için mevcut istek sayısı? (Belgeleri kontrol edin)
"remaining": 95, // Kullanıcının gün/dönem için kalan indirme kotası
"message": "Download count successful.",
"reset_time": "2023-10-27T12:00:00Z", // İndirme kotasının sıfırlanabileceği zaman
"reset_time_utc": "2023-10-27T12:00:00Z"
}
İndirmeyi İşleme:
Doğru file_id ile /download'e POST isteği gönderin. Başarı için yanıt durum kodunu kontrol edin (örneğin, 200 OK). JSON yanıtından link değerini çıkarın. Bu link URL'sine standart bir HTTP GET isteği gönderin. Bu istek genellikle API Anahtarı veya Yetkilendirme başlıklarını gerektirmez, çünkü bağlantının kendisi önceden yetkilendirilmiştir. link URL'sindeki GET isteğine verilen yanıt, gerçek altyazı dosyası içeriği olacaktır (örneğin, SRT dosyasının metni). Bu içeriği bir dosyaya kaydedin (örneğin, sağlanan file_name'i kullanarak).
Önemli: İndirme bağlantıları (link) genellikle geçicidir ve kısa bir süre veya belirli sayıda kullanımdan sonra süresi dolabilir. Bu bağlantıları uzun süreli kullanım için saklamayın; her indirme gerektiğinde /download uç noktası aracılığıyla yeni bir bağlantı alın. Ayrıca, kullanıcının kotasını tüketmemek için remaining indirme sayısını izleyin.
Gelişmiş Özellikler: AI Çevirisi (/ai-translation)
OpenSubtitles araç setine daha yeni eklenen bir özellik, AI destekli çeviri özelliğidir.
Uç Nokta: POST /ai-translation (veya benzeri, belgelerdeki tam uç noktayı kontrol edin)
Amaç: Mevcut bir altyazı dosyasını, AI modellerini kullanarak başka bir dile çevirmek.
Nasıl Çalışır (Kavramsal):
Çevirmek istediğiniz kaynak altyazının file_id'sini sağlamanız muhtemeldir. target_language'i belirtirsiniz (örneğin, Almanca için target_language=de). API isteği işler, potansiyel olarak çeviri işini sıraya alır. Yanıt, iş durumunu gösterebilir veya tamamlandıktan sonra çevrilmiş altyazı için yeni bir file_id veya indirme bağlantısı sağlayabilir.
Kullanım Alanları:
Altyazıları, veritabanında başlangıçta bulunmayan dillerde kullanılabilir hale getirmek. Uygulamanız içinde kullanıcılara isteğe bağlı çeviri seçenekleri sunmak.
Dikkat Edilmesi Gerekenler:
AI çevirileri, VIP veya abonelik katmanlarına bağlı olarak, ilişkili maliyetlere veya belirli hız sınırlarına/kotalara sahip olabilir. AI çevirisinin kalitesi, dil çiftine ve kaynak metnin karmaşıklığına bağlı olarak değişebilir. Bu özellik, belirli kullanıcı izinleri veya abonelik seviyeleri gerektirebilir. Kullanım, parametreler ve sınırlamalar hakkında ayrıntılar için API belgelerine bakın.
API Entegrasyonu için En İyi Uygulamalar
Uygulamanızın OpenSubtitles API ile sorunsuz ve sorumlu bir şekilde etkileşim kurmasını sağlamak için, bu en iyi uygulamaları izleyin:
Yanıtları Önbelleğe Alın: Özellikle hızla değişmeyen arama sonuçları (/subtitles) için. Bir kullanıcı aynı filmi/bölümü birden çok kez ararsa, API'ye tekrar tekrar ulaşmak yerine önbelleğe alınmış sonucu sunun. Makul son kullanma süreleriyle akıllı önbelleğe alma uygulayın. Hız Sınırlarına Uyun: X-RateLimit-* ve Retry-After başlıklarını aktif olarak izleyin. Sınıra ulaşırsanız, üstel geri alma stratejileri uygulayın (tekrarlanan hız sınırlamasından sonra daha uzun süre bekleyin). API'yi agresif bir şekilde yoklamayın. Belirli Tanımlayıcılar Kullanın: Mümkün olduğunda, query yerine imdb_id veya tmdb_id kullanarak arama yapın. Bunlar çok daha doğru sonuçlar sağlar ve belirsizliği azaltır. Video dosyası mevcutsa, en yüksek doğruluk için moviehash kullanın. Açık Bir User-Agent Sağlayın: Benzersiz ve açıklayıcı bir User-Agent dizesi kullanın (örneğin, MyMediaPlayerApp/2.1 (contact@myapp.com)). Bu, OpenSubtitles'ın trafik kaynaklarını belirlemesine ve sorunları gidermesine yardımcı olur. Genel ajanlar engellenebilir. Hataları Zarif Bir Şekilde İşleyin: Her yanıt için HTTP durum kodlarını kontrol edin. 401 Unauthorized (geçersiz API Anahtarı/JWT), 403 Forbidden (izin reddedildi), 404 Not Found, 429 Too Many Requests ve 5xx sunucu hataları gibi yaygın hataları işlemek için mantık uygulayın. Kullanıcıya bilgilendirici geri bildirim sağlayın. İndirme Kotalarını Yönetin: Kullanıcının hesabıyla (veya API anahtarıyla) ilişkili günlük/periyodik indirme sınırlarına dikkat edin. Kotasına yaklaşıyorlarsa veya kotasını aşmışlarsa kullanıcıları bilgilendirin. /download yanıtında remaining alanını kullanın. Aramaları Optimize Edin: Gereksiz veri istemeyin. Sonuçları sunucu tarafında daraltmak için languages, type, hearing_impaired vb. gibi parametreleri kullanın, büyük veri kümelerini istemci tarafında filtrelemek yerine. API Anahtarınızı Güvenceye Alın: API Anahtarınıza bir şifre gibi davranın. İstemci tarafı koduna doğrudan gömmeyin. Sunucunuzda güvenli bir şekilde saklayın.
Sarmalayıcılar, Betikler ve Topluluk Kaynakları
Bu kılavuz doğrudan API etkileşimini kapsarken, OpenSubtitles ekosistemi genellikle topluluk tarafından geliştirilen kaynakları içerir.
API Sarmalayıcıları: GitHub veya paket yöneticileri (PyPI, npm) gibi platformlarda programlama diliniz (örneğin, Python, JavaScript, Java) için kitaplıklar veya SDK'lar arayın. Bu sarmalayıcılar, API çağrılarını basitleştirebilir, kimlik doğrulamasını işleyebilir ve yanıtları ayrıştırabilir. Betikler: API ile etkileşim kurmak için çeşitli komut satırı araçları veya betikler mevcut olabilir, otomasyon veya hızlı aramalar için kullanışlıdır. Forumlar/Topluluklar: API'yi kullanan tartışmalar, örnekler ve potansiyel üçüncü taraf araçları için OpenSubtitles forumlarını veya ilgili geliştirici topluluklarını kontrol edin.
İyi bakımı yapılan bir sarmalayıcı kullanmak, geliştirmeyi önemli ölçüde hızlandırabilir, ancak temel API çağrılarını (bu kılavuzda açıklandığı gibi) anlamak, sorun giderme ve gelişmiş kullanım için çok önemlidir.
API Aboneliği ve Fiyatlandırma
OpenSubtitles genellikle API'sine farklı erişim seviyeleri sunar:
Ücretsiz Katman: Genellikle daha katı hız sınırları ve indirme kotaları ile temel erişim sağlar. Düşük hacimli uygulamalar veya geliştirme/test için uygundur. VIP/Ücretli Katmanlar: Önemli ölçüde daha yüksek hız sınırları, daha büyük indirme kotaları, premium özelliklere erişim (potansiyel olarak AI Çevirisi veya daha hızlı destek gibi) sunar ve ticari veya yüksek trafikli uygulamalar için tasarlanmıştır.
Abonelik planları, fiyatlandırma ve her katmanla ilişkili belirli sınırlar/özellikler hakkında en güncel ayrıntılar için resmi OpenSubtitles API belgelerine veya web sitesine bakın. Uygulamanızın beklenen kullanımına ve özellik gereksinimlerine en uygun planı seçin.
Sonuç
OpenSubtitles API, dünyanın en büyük altyazı koleksiyonlarından birine güçlü bir geçittir. Yapısını, kimlik doğrulama yöntemlerini, /subtitles ve /download gibi temel uç noktalarını anlayarak ve en iyi uygulamalara uyarak, geliştiriciler altyazı işlevselliğini uygulamalarına sorunsuz bir şekilde entegre edebilirler. Medya oynatıcılardaki basit aramalardan, AI çevirisi içeren karmaşık özelliklere kadar, API yenilikçi ve kullanıcı dostu deneyimler için yapı taşlarını sağlar. Geliştirme yolculuğunuza başlarken, en güncel uç nokta ayrıntıları, parametreler ve politikalar için resmi OpenSubtitles API belgelerine başvurmayı unutmayın. İyi kodlamalar!
