YouTube 자막 API가 작동하지 않나요? 진단 체크리스트

진단 체크리스트

에러 코드(또는 응답의 형태)를 아래 표와 비교해 보세요.

AWS, GCP, Azure, 또는 VPS에서 차단되었나요?

스크립트가 노트북에서는 완벽히 작동하다가 클라우드 서버에 배포하는 순간 실패한다면, 거의 항상 이 때문입니다: YouTube의 자막 가져오기 엔드포인트는 개별적인 악성 IP뿐 아니라 데이터센터 IP 대역 전체를 차단합니다. 수천 개의 무관한 스크립트가 같은 주소 대역을 공유하기 때문에, 모든 주요 클라우드 제공업체의 IP 공간이 결국 이 문제를 겪게 됩니다.

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.

현실적인 우회 방법을, 대략 노력이 적은 순서대로 정리하면:

• 레지덴셜 또는 모바일 프록시 풀을 통해 요청을 우회 - 어느 정도는 작동하지만, 유료 로테이팅 레지덴셜 설정조차 여전히 실패한다는 보고가 점점 늘고 있습니다. 영구적인 해결책은 아닙니다.
• 여러 클라우드 제공업체나 리전을 번갈아 사용 - 그 대역도 결국 표시되기 전까지 시간을 법니다.
• 같은 동영상을 다시 가져오지 않도록 적극적으로 캐싱 - 차단에 걸리는 빈도는 줄이지만 없애지는 못합니다.
• 이 인프라를 이미 운영하는 호스팅된 API를 사용 - 문제가 '내 프로젝트'에서 '이걸 계속 작동시키는 게 실제 업무인 누군가'에게로 넘어갑니다.

그것이 바로 저희 자체 YouTube 자막 API가 채우는 진짜 공백입니다 - 다른 라이브러리가 아니라, 정확히 이 문제를 위해 이미 구축된 인프라입니다.

PoTokenRequired가 발생하나요?

더 최근의 실패 유형입니다: YouTube의 자막 엔드포인트는 점점 더 자체 플레이어 JavaScript가 런타임에 생성하는 출처 증명 토큰을 요구합니다 - 쿠키도, IP 평판 검사도 아닌 암호학적 값입니다. 단순한 HTTP 요청으로는 이를 생성할 방법이 없습니다.

실제 기술적 세부사항은 jdepoix/youtube-transcript-api#592에서 확인하세요 - 해당 보고 시점 기준으로, 오픈소스 라이브러리에는 문서화된 우회 방법이 없습니다.

이것이 바로 호스팅된 API가 흡수하도록 만들어진 종류의 문제입니다 - 엔드포인트 하나만 호출하면 토큰 생성 문제를 직접 해결할 필요 없이 자막이나 명확한 에러를 돌려받습니다.

각 실패에 대해 저희 자체 API가 반환하는 것

이미 저희 API를 사용 중이고 HTTP 상태만으로 추측하는 대신 정확한 실패에 따라 분기하고 싶다면, 모든 에러는 안정적인 `code` 필드와 함께 반환됩니다:

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." }

전체 파라미터 참조와 모든 상태 코드는 API 문서에 있습니다.