API Transkrip YouTube Tidak Berfungsi? Daftar Periksa Diagnostik
Setiap alasan nyata mengapa permintaan transkrip gagal, disusun dari isu paling banyak dibahas oleh komunitas open-source sendiri - bukan tebakan - lengkap dengan kode error yang tepat dan solusinya.
Daftar periksa diagnostik
Cocokkan kode error Anda (atau bentuk respons Anda) dengan tabel di bawah.
| Kode | Artinya | Yang harus dilakukan |
|---|---|---|
MISSING_URL / INVALID_URL · 400 | Parameter v hilang, atau bukan ID/URL video yang dikenali YouTube. | Kirim ID video 11 karakter yang valid atau URL lengkap youtube.com/watch?v=... |
VIDEO_UNAVAILABLE · 404 | Video bersifat privat, telah dihapus, atau dikunci wilayah - tidak ada dari sudut pandang server. | Pastikan dulu video bisa dimuat di browser biasa. Jika tidak bisa, tidak ada yang bisa diambil API. |
TRANSCRIPT_DISABLED · 404 | Biasanya berarti pengunggah menonaktifkan teks, tetapi kunci wilayah dan blokir IP bisa menghasilkan error yang terlihat sama persis. | Lihat catatan di bawah sebelum menganggapnya permanen. |
LANGUAGE_NOT_AVAILABLE · 404 | Video memiliki teks, hanya saja bukan dalam bahasa yang diminta. | Hapus parameter bahasa untuk mendapatkan apa pun yang tersedia, atau periksa dulu daftar teks video itu sendiri. |
TRANSCRIPT_NOT_FOUND · 404 | Tidak ada transkrip dalam bahasa apa pun untuk video ini. | Sama seperti teks yang dinonaktifkan - tidak ada yang bisa diambil. Tidak semua video memilikinya. |
RATE_LIMITED · 429 | Kunci API Anda membuat lebih banyak permintaan daripada batas per menit paket Anda. | Perlambat dan coba lagi, atau tingkatkan ke batas kecepatan yang lebih tinggi. |
UPSTREAM_* · 429/503/504 | Masalah sementara saat berkomunikasi dengan YouTube sendiri, bukan kunci atau permintaan Anda. | Aman dicoba lagi setelah jeda singkat - persis jenis kegagalan yang diserap API terhosting untuk Anda. |
"Teks dinonaktifkan" tidak selalu berarti dinonaktifkan
Isu paling banyak dibahas dalam sejarah youtube-transcript-api open-source (187 komentar) adalah skrip yang memunculkan "TranscriptsDisabled" untuk video yang sebenarnya tidak dinonaktifkan - teksnya diputar normal di browser biasa. Tiga penyebab nyata berbeda menghasilkan error yang hampir identik:
- Benar-benar dinonaktifkan - pengunggah mematikan teks. Tidak ada yang bisa diambil, dalam bahasa apa pun.
- Dikunci wilayah - video atau teksnya tidak tersedia dari negara server Anda, tetapi berfungsi dari browser di wilayah lain.
- Diblokir IP - YouTube mengembalikan kegagalan generik alih-alih yang spesifik, dan penyebab sebenarnya adalah masalah hosting cloud di bawah ini.
Error parsing XML mentah ("no element found", "line 1, column 0") alih-alih pengecualian yang bersih adalah masalah dari keluarga yang sama - badan respons kosong, biasanya karena penyebab blokir IP atau PoToken yang sama di bawah, bukan bug pada kode parsing itu sendiri.
Diblokir di AWS, GCP, Azure, atau VPS?
Jika skrip berjalan sempurna di laptop Anda lalu gagal begitu di-deploy ke server cloud, hampir selalu ini penyebabnya: endpoint pengambilan teks YouTube memblokir seluruh rentang IP datacenter, bukan hanya IP individu yang menyalahgunakan. Ruang IP setiap penyedia cloud besar akhirnya terkena ini, karena ribuan skrip yang tidak berhubungan berbagi rentang alamat yang sama.
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.Cara realistis untuk mengatasinya, kira-kira berurutan dari yang paling mudah:
- Alihkan permintaan lewat pool proxy residensial atau seluler - terkadang berhasil, tetapi laporan bahwa bahkan setup residensial berputar berbayar tetap gagal semakin sering. Bukan solusi permanen.
- Bergantian antar beberapa penyedia cloud atau wilayah - membeli waktu sampai rentang itu juga ditandai.
- Cache secara agresif agar tidak mengambil ulang video yang sama - mengurangi seberapa sering Anda terkena blokir, tidak menghilangkannya.
- Gunakan API terhosting yang sudah menjalankan infrastruktur ini - masalahnya berpindah dari 'proyek Anda' ke 'seseorang yang pekerjaan sebenarnya adalah menjaga ini tetap berjalan'.
Itulah celah nyata yang diisi oleh API Transkrip YouTube kami sendiri - bukan pustaka lain, tetapi infrastruktur yang memang sudah dibangun khusus untuk masalah ini.
Mendapatkan PoTokenRequired?
Mode kegagalan yang lebih baru: endpoint teks YouTube semakin memerlukan token bukti asal yang dihasilkan saat runtime oleh JavaScript pemutarnya sendiri - bukan cookie, bukan pemeriksaan reputasi IP, melainkan nilai kriptografis. Permintaan HTTP biasa tidak punya cara untuk menghasilkannya.
Lihat detail teknis nyatanya di jdepoix/youtube-transcript-api#592 - per laporan tersebut, tidak ada solusi terdokumentasi di pustaka open-source.
Ini persis jenis masalah yang seharusnya diserap oleh API terhosting - panggil satu endpoint dan dapatkan transkrip atau error yang jelas, tanpa perlu memecahkan sendiri pembuatan token.
Apa yang dikembalikan API kami sendiri untuk setiap kegagalan
Jika Anda sudah menggunakan API kami dan ingin menentukan cabang berdasarkan kegagalan yang tepat alih-alih menebak hanya dari status HTTP, setiap error kembali dengan field `code` yang stabil:
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." }Referensi parameter lengkap dan setiap kode status ada di dokumentasi API.
Error Umum API Transkrip YouTube
Kenapa saya mendapat 'YouTube is blocking requests from your IP'?
Anda memanggil endpoint teks YouTube dari alamat IP cloud/datacenter (AWS, GCP, Azure, VPS...), dan YouTube memblokir rentang tersebut lebih agresif daripada IP rumah/residensial. Biasanya bukan hal pribadi - ini seluruh rentang IP, dibagi dengan ribuan skrip lain.
Kenapa skrip saya berjalan secara lokal tapi gagal setelah di-deploy?
Laptop Anda memiliki IP residensial; server Anda memiliki IP datacenter. Kode yang sama, reputasi jaringan berbeda - penyebab paling umum "berhasil di sini, gagal di sana" bagi siapa pun yang meng-hosting sendiri pustaka transkrip YouTube.
Kenapa 'teks dinonaktifkan' terkadang ternyata salah?
Karena YouTube tidak selalu mengembalikan alasan spesifik - kunci wilayah atau blokir IP bisa menghasilkan error generik yang sama seperti video yang benar-benar dinonaktifkan. Periksa apakah video memutar teks di browser normal dari jaringan lain sebelum menganggapnya tidak tersedia secara permanen.
Apa itu PoTokenRequired?
YouTube mensyaratkan token bukti asal yang dihasilkan oleh JavaScript pemutar asli saat runtime, bukan nilai statis yang bisa di-hardcode atau diekstrak sekali. Permintaan HTTP biasa - dan sebagian besar pustaka scraping - tidak punya cara menghasilkannya, itu sebabnya saat ini tidak ada solusi terdokumentasi di pustaka open-source.
Kenapa tidak ada transkrip dalam bahasa yang saya minta?
Video memiliki teks, hanya saja bukan bahasa itu. Minta tanpa parameter bahasa untuk mendapatkan apa pun yang tersedia, atau periksa dulu bahasa apa saja yang ada.
Bagaimana cara menghindari batas kecepatan?
Ada dua batas berbeda: batas permintaan per menit paket Anda sendiri (tingkatkan untuk yang lebih tinggi), dan batas upstream YouTube sendiri (aman dicoba lagi setelah jeda singkat - API terhosting menyerap sebagian besar ini untuk Anda).