YouTube Transkript API Çalışmıyor mu? Tanı Kontrol Listesi
Bir transkript isteğinin başarısız olmasının her gerçek nedeni, tahminlere değil açık kaynak topluluğunun kendi en çok tartışılan sorunlarına dayanarak hazırlandı - her biri için tam hata kodu ve çözümüyle birlikte.
Tanı kontrol listesi
Hata kodunuzu (veya yanıtınızın şeklini) aşağıdaki tabloyla karşılaştırın.
| Kod | Ne anlama gelir | Ne yapmalı |
|---|---|---|
MISSING_URL / INVALID_URL · 400 | v parametresi eksik, ya da YouTube'un tanıdığı bir video kimliği/URL'si değil. | Geçerli 11 karakterlik bir video kimliği veya tam bir youtube.com/watch?v=... URL'si gönderin. |
VIDEO_UNAVAILABLE · 404 | Video özel, silinmiş ya da bölge kilitli - sunucunun bakış açısından mevcut değil. | Önce videonun normal bir tarayıcıda yüklendiğini doğrulayın. Yüklenmiyorsa, bir API'nin alabileceği hiçbir şey yok demektir. |
TRANSCRIPT_DISABLED · 404 | Genellikle yükleyicinin altyazıları devre dışı bıraktığı anlamına gelir - ama bölge kilitleri ve IP engelleri de aynı görünen bir hata üretebilir. | Kalıcı olduğunu varsaymadan önce aşağıdaki uyarıya bakın. |
LANGUAGE_NOT_AVAILABLE · 404 | Videoda altyazı var, sadece istediğiniz dilde değil. | Mevcut olanı almak için dil parametresini kaldırın, ya da önce videonun kendi altyazı listesini kontrol edin. |
TRANSCRIPT_NOT_FOUND · 404 | Bu video için hiçbir dilde transkript mevcut değil. | Devre dışı bırakılmış altyazılarla aynı durum - alınacak bir şey yok. Her videoda bu olmuyor. |
RATE_LIMITED · 429 | API anahtarınız, planınızın dakika başına limitinin izin verdiğinden daha fazla istek yaptı. | Yavaşlayıp yeniden deneyin, ya da daha yüksek bir hız limiti için yükseltin. |
UPSTREAM_* · 429/503/504 | Anahtarınız veya isteğinizle değil, doğrudan YouTube ile konuşurken yaşanan geçici bir sorun. | Kısa bir bekleme sonrası yeniden denemek güvenli - tam olarak barındırılan bir API'nin sizin yerinize absorbe ettiği türden bir hata. |
"Transkript devre dışı" her zaman devre dışı anlamına gelmez
Açık kaynak youtube-transcript-api'nin tüm tarihindeki en çok tartışılan sorun (187 yorum), gerçekte devre dışı olmayan bir video için bir betiğin "TranscriptsDisabled" hatası vermesidir - normal bir tarayıcıda altyazılar sorunsuz oynar. Üç farklı gerçek neden neredeyse aynı görünen bir hata üretir:
- Gerçekten devre dışı - yükleyici altyazıları kapattı. Hiçbir dilde alınacak bir şey yok.
- Bölge kilitli - video veya altyazıları sunucunuzun ülkesinden erişilebilir değil, ama başka bir bölgedeki tarayıcıdan çalışıyor.
- IP engelli - YouTube belirli bir hata yerine genel bir hata döndürüyor, ve gerçek neden aşağıdaki bulut barındırma sorunu.
Temiz bir istisna yerine ham bir XML ayrıştırma hatası ("no element found", "line 1, column 0") almak da aynı problem ailesinden - boş bir yanıt gövdesi, genellikle aşağıdaki aynı IP engeli veya PoToken nedeniyle, ayrıştırma kodunun kendisindeki bir hata değil.
AWS, GCP, Azure veya bir VPS'te engellendiniz mi?
Bir betik dizüstü bilgisayarınızda kusursuz çalışıp bir bulut sunucusuna dağıtılır dağıtılmaz başarısız oluyorsa, neredeyse her zaman şu yüzdendir: YouTube'un altyazı alma endpoint'i, yalnızca kötüye kullanan tekil IP'leri değil, tüm veri merkezi IP aralıklarını engeller. Binlerce ilgisiz betik aynı adres aralıklarını paylaştığı için, her büyük bulut sağlayıcısının IP alanı er ya da geç buna maruz kalır.
Could not retrieve a transcript for the video https://www.youtube.com/watch?v=...!
This is most likely caused by:
YouTube is blocking requests from your IP.Gerçekçi çözüm yolları, yaklaşık olarak çaba sırasına göre:
- İstekleri bir konut veya mobil proxy havuzu üzerinden yönlendirin - bazen işe yarar, ama ücretli dönen konut proxy kurulumlarının bile hala başarısız olduğuna dair raporlar giderek artıyor. Kalıcı bir çözüm değil.
- Birden fazla bulut sağlayıcısı veya bölge arasında dönüşümlü çalışın - bu aralıklar da işaretlenene kadar zaman kazandırır.
- Aynı videoları tekrar çekmemek için agresif bir şekilde önbelleğe alın - engele takılma sıklığını azaltır, ortadan kaldırmaz.
- Bu altyapıyı zaten çalıştıran barındırılan bir API kullanın - sorun 'sizin projeniz'den, 'gerçek işi bunu çalışır tutmak olan birine' taşınır.
Kendi YouTube Transkript API'mizin doldurduğu gerçek boşluk tam olarak bu - farklı bir kütüphane değil, tam olarak bu sorun için zaten inşa edilmiş bir altyapı.
PoTokenRequired mi alıyorsunuz?
Daha yeni bir hata türü: YouTube'un altyazı endpoint'i giderek kendi oynatıcı JavaScript'i tarafından çalışma zamanında üretilen bir köken kanıtı token'ı gerektiriyor - bir çerez değil, bir IP itibar kontrolü değil, kriptografik bir değer. Basit bir HTTP isteğinin bunu üretmesinin bir yolu yok.
Gerçek teknik ayrıntıyı jdepoix/youtube-transcript-api#592'de görün - bu rapora göre, açık kaynak kütüphanede belgelenmiş bir çözüm yok.
Bu, barındırılan bir API'nin absorbe etmesi gereken tam olarak bu tür bir sorun - bir endpoint çağırın ve token üretimini kendiniz çözmek zorunda kalmadan bir transkript ya da net bir hata alın.
Kendi API'miz her hata için ne döndürüyor
Zaten API'mizi kullanıyorsanız ve yalnızca HTTP durumundan tahmin etmek yerine tam hataya göre dallanmak istiyorsanız, her hata sabit bir `code` alanıyla birlikte döner:
curl "https://getyoutubetranscript.com/api/v1/transcript?v=dQw4w9WgXcQ" \
-H "Authorization: Bearer sk_live_..."
# A failure looks like:
# { "success": false, "code": "TRANSCRIPT_DISABLED", "message": "Transcripts are disabled for this video." }Tam parametre referansı ve her durum kodu API belgelerinde yer alır.
Yaygın YouTube Transkript API Hataları
Neden 'YouTube is blocking requests from your IP' hatası alıyorum?
YouTube'un altyazı endpoint'ini bir bulut/veri merkezi IP adresinden (AWS, GCP, Azure, bir VPS...) çağırıyorsunuz ve YouTube bu aralıkları ev/konut IP'lerine göre daha agresif şekilde engelliyor. Genellikle kişisel değildir - binlerce başka betikle paylaşılan tüm IP aralığıdır.
Betiğim neden yerelde çalışıyor ama dağıtınca başarısız oluyor?
Dizüstü bilgisayarınızda konut IP'si var; sunucunuzda veri merkezi IP'si var. Aynı kod, farklı ağ itibarı - kendi YouTube transkript kütüphanesini barındıran herkes için "burada çalışıyor, orada başarısız oluyor" durumunun en yaygın nedeni.
'Transkript devre dışı' neden bazen yanlış çıkıyor?
Çünkü YouTube her zaman belirli bir neden döndürmez - bir bölge kilidi veya IP engeli, gerçekten devre dışı bırakılmış bir videoyla aynı genel hatayı üretebilir. Kalıcı olarak kullanılamaz olduğunu varsaymadan önce, videonun başka bir ağdan normal bir tarayıcıda altyazı oynatıp oynatmadığını kontrol edin.
PoTokenRequired nedir?
YouTube'un, çalışma zamanında gerçek oynatıcı JavaScript'i tarafından üretilen bir köken kanıtı token'ı istemesi - sabit kodlayabileceğiniz veya bir kez çıkarabileceğiniz statik bir değer değil. Basit HTTP istekleri - ve çoğu scraping kütüphanesi - bunu üretmenin bir yoluna sahip değil, bu yüzden şu anda açık kaynak kütüphanede belgelenmiş bir çözüm yok.
İstediğim dilde neden transkript yok?
Videoda altyazı var, sadece o dilde değil. Mevcut olanı almak için dil parametresi olmadan istek yapın, ya da önce hangi dillerin var olduğunu kontrol edin.
Hız limitlerinden nasıl kaçınırım?
İki farklı limit var: kendi planınızın dakika başına istek üst sınırı (daha yüksek biri için yükseltin) ve YouTube'un kendi upstream limitleri (kısa bir bekleme sonrası yeniden denemek güvenli - barındırılan bir API bunun çoğunu sizin yerinize absorbe eder).