Transkrip dengan YouTube Data API: Mengapa captions.download Gagal

Terminal menampilkan respons 403 Forbidden dari endpoint captions.download YouTube Data API

Jika Anda mencoba mendapatkan transkrip lewat YouTube Data API, Anda mungkin sudah menabrak temboknya: captions.list dengan riang mengembalikan ID track caption untuk video apa pun, tetapi begitu Anda memanggil captions.download pada salah satunya, Anda mendapat 403. Anda memeriksa ulang API key, menambahkan scope youtube.force-ssl, mencoba OAuth — tetap 403. Ini bukan bug dan bukan masalah kuota. Ini memang disengaja, dan dokumentasinya mengubur poin utamanya.

Pembatasannya, secara persis

captions.download memerlukan token OAuth dari akun yang memiliki video tersebut. Bukan sembarang akun yang terautentikasi — pemilik kanal (atau content manager yang punya hak atasnya). Endpoint captions ada agar kreator dapat mengelola track subtitle di unggahan mereka sendiri: mengunggah .srt, memperbaiki typo, menghapus terjemahan otomatis yang buruk. Mengunduh caption dari video pihak ketiga sembarangan tidak pernah menjadi bagian dari kontraknya.

Pesan error-nya menjelaskan semuanya begitu Anda membacanya dengan cermat:

The permissions associated with the request are not sufficient
to download the caption track.

Jadi jalur eskalasi yang biasa — API key → OAuth sebagai diri sendiri → scope yang lebih luas → service account — tidak membawa ke mana-mana. Setiap anak tangga gagal pada pemeriksaan kepemilikan yang sama. Saya menghabiskan setengah hari untuk ini sebelum menerimanya, dan dilihat dari lalu lintas Stack Overflow, begitu pula separuh internet.

Untuk apa captions.list masih berguna

Agar adil terhadap Data API: captions.list bekerja dengan API key biasa dan memakan sekitar 50 unit kuota. Ia memberi tahu track mana yang ada, bahasanya, dan apakah dihasilkan otomatis (trackKind: "asr") atau diunggah manusia. Itu benar-benar berguna sebagai pemeriksaan awal — jika sebuah video tidak punya track sama sekali, Anda tahu sejak awal bahwa Anda akan membutuhkan speech-to-text alih-alih ekstraksi caption. Data API juga tetap merupakan alat yang tepat untuk pencarian, enumerasi playlist, dan metadata. Ia hanya tidak akan menyerahkan teks transkripnya.

Opsi 1: ambil caption dengan cara yang dilakukan player

Player video jelas menerima data caption tanpa token OAuth pemiliknya, dan library seperti youtube-transcript-api (Python) mengambilnya dengan cara yang sama. Di laptop Anda ini bekerja dengan baik dan hanya butuh tiga baris.

Peringatannya muncul di produksi: YouTube secara agresif menantang request dari rentang IP datacenter. Deploy tiga baris yang sama ke AWS, GCP, atau Heroku dan Anda akan mulai melihat "Sign in to confirm you're not a bot" dan error IpBlocked. Saya sudah menuliskan mode kegagalan itu beserta solusinya secara terpisah di mengapa youtube-transcript-api diblokir di cloud — versi singkatnya: bisa diatasi dengan residential proxy, tetapi itu proyek tersendiri.

Opsi 2: transcript API yang di-hosting

Jika Anda hanya ingin teks dari sebuah URL, endpoint yang di-hosting melewati kedua masalah itu — tanpa syarat kepemilikan, tanpa mengasuh proxy. youtube2text.org menjalankan pengambilan caption di balik rotating residential proxy di sisi server, jadi request Anda boleh datang dari mana saja:

# grab a free demo key (shared, 5 videos/month per IP)
curl -s https://youtube2text.org/api/demo-key

# fetch a transcript
curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -H "x-api-key: yt_YOUR_KEY"

Responsnya JSON polos:

{"result": {"videoId": "...", "title": "...", "pubDate": "...",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Jika videonya memang tidak punya caption, Anda mendapat TRANSCRIPT_UNAVAILABLE dengan 404 — situasi yang sama yang akan ditampilkan captions.list sebagai daftar track kosong, hanya saja terdeteksi dalam satu panggilan alih-alih dua.

Ada panduan yang lebih panjang dengan penanganan error di mengekstrak transkrip YouTube dengan curl, dan versi Python di panduan migrasi youtube-transcript-api jika kode berbasis requests lebih cocok untuk Anda.

Setup gabungan yang masuk akal

Yang benar-benar akan saya bangun hari ini, setelah bergulat dengan ini dari kedua sisi:

Data API untuk penemuan — pencarian, unggahan kanal, playlist, tanggal terbit. Ia andal dan kuotanya lega untuk metadata.
Endpoint transkrip (di-hosting, atau scraping sendiri dengan proxy jika Anda menikmatinya) untuk teks yang sebenarnya.
Speech-to-text sebagai fallback hanya untuk video tanpa caption sama sekali.

Memaksa captions.download melakukan pekerjaan yang di tengah adalah satu-satunya jalur yang secara kategoris tidak mungkin berhasil untuk video yang bukan milik Anda — tidak ada scope, key, atau pengaturan console yang mengubahnya.

Jika Anda ingin key sendiri alih-alih demo key bersama, masuknya hanya lewat Google di youtube2text.org/app/keys — tanpa nomor telepon, tanpa kartu. Paket gratis 5 video/bulan; paket berbayar mulai dari $5,99 untuk 50.