youtube-transcript-api는 유튜브 영상의 자막을 가져오는 무료 오픈소스 파이썬 라이브러리입니다. pip install youtube-transcript-api 후 YouTubeTranscriptApi().fetch(video_id)를 호출하면 됩니다. 내 컴퓨터에서는 잘 작동하지만 클라우드 서버에서는 유튜브가 RequestBlocked나 IpBlocked로 자주 차단하며, 자막 없는 영상에는 쓸 수 없습니다.
2026년 11월 21일 클라우드 서버에서 실행해 본 뒤, 같은 서버에서 같은 두 영상을 저희 호스팅 API로 처리했습니다. 각각 어떻게 됐는지, 라이브러리 사용법, 그리고 호스팅 API가 더 나은 경우를 정리했습니다.
youtube-transcript-api란?
Jonas Depoix가 만든 파이썬 라이브러리로, GitHub와 PyPI에 공개되어 있고 MIT 라이선스입니다. 현재 버전은 1.2.5이며 파이썬 3.8 이상을 지원합니다.
- 유튜브에 이미 있는 자막, 즉 채널이 올린 자막이나 유튜브 자동 자막을 읽습니다.
- API 키도 헤드리스 브라우저도 필요 없습니다.
- 영상의 자막 언어 목록 조회, 언어 우선순위 지정, 유튜브 기계 번역 사용이 가능합니다.
- 텍스트, JSON, SRT, WebVTT로 출력하며 명령줄 도구도 있습니다.
README는 장단점을 솔직하게 밝힙니다. 유튜브 웹 플레이어의 문서화되지 않은 부분을 쓰기 때문에 "no guarantee that it won't stop working tomorrow"라고 합니다.
어떻게 사용하나요?
pip install youtube-transcript-api
from youtube_transcript_api import YouTubeTranscriptApi
from youtube_transcript_api.formatters import SRTFormatter
ytt_api = YouTubeTranscriptApi()
# English if it exists, else German
transcript = ytt_api.fetch("aircAruvnKk", languages=["en", "de"])
for snippet in transcript:
print(snippet.start, snippet.text)
print(SRTFormatter().format_transcript(transcript))
명령줄에서는 youtube_transcript_api aircAruvnKk --languages en --format json > transcript.json로 같은 작업을 합니다. 언어 목록, 번역 등은 README에 나와 있습니다.
왜 내 서버에서 IpBlocked로 실패하나요?
유튜브가 클라우드 업체에서 오는 요청 대부분을 차단하기 때문입니다. 라이브러리 README에 분명히 적혀 있습니다. 유튜브는 "has started blocking most IPs that are known to belong to cloud providers (like AWS, Google Cloud Platform, Azure, etc.)" 그래서 코드를 배포하면 "most likely" RequestBlocked나 IpBlocked 오류를 만나게 된다고요. 가정용 IP도 요청이 너무 많으면 차단될 수 있습니다.
저희도 직접 확인했습니다. 2026년 11월 21일 클라우드 서버에 1.2.5 버전을 설치하고 공개 강의 두 편을 요청했습니다.
같은 서버, 같은 두 영상, 2026년 11월 21일(UTC).
두 호출 모두 약 1.1초 만에 IpBlocked가 났습니다. 같은 서버에서 youtube.com에 그냥 접속해도 구글의 "비정상적인 트래픽" 페이지로 리디렉션됐습니다. 라이브러리 버그가 아니라 유튜브가 서버를 거부한 것입니다.
README의 해결책은 프록시이며, 고정 프록시는 오래 쓰면 유튜브가 차단하기 때문에 순환형 주거용 프록시를 권합니다. 효과는 있지만 유료 서비스와 계정이 하나씩 늘고 차단 여부를 계속 지켜봐야 합니다.
또 무엇 때문에 멈출 수 있나요?
- 자막 없음. 이 라이브러리는 자막을 읽을 뿐 음성을 변환하지 않습니다. 자막이 꺼져 있으면
TranscriptsDisabled, 언어가 없으면NoTranscriptFound가 납니다. - 연령 제한 영상. README에 따르면 이런 영상에 필요한 쿠키 로그인은 유튜브 측 변경 이후 "currently not available"입니다.
- 유튜브의 변경. 문서화되지 않은 인터페이스를 쓰기 때문에 유튜브 업데이트로 새 버전이 나올 때까지 작동하지 않을 수 있습니다.
노트북에서 스크립트를 돌리는 데는 이 중 어느 것도 문제가 되지 않습니다. 하지만 제품에 넣기 전에는 미리 대비해야 합니다.
차단되면 무엇을 대신 쓰나요?
자기 쪽에서 가져오는 일을 처리하는 호스팅 스크립트 API입니다. 저희 것은 YouTubeTranscript.dev API입니다. 같은 클라우드 서버에서 몇 분 전에 같은 두 영상을 처리한 결과입니다.
| 영상 | 길이 | 시간 | 단어 수 | 타임스탬프 줄 수 | 크레딧 |
|---|---|---|---|---|---|
| But what is a neural network? (3Blue1Brown) | 18:40 | 4.2초 | 3,357 | 286 | 1 |
| 1. What is Computation? (MIT OpenCourseWare) | 43:06 | 4.2초 | 6,363 | 887 | 1 |
| 같은 3Blue1Brown 영상을 다시 요청 | 18:40 | 1.3초 | 3,357 | 286 | 0 |
측정 방법: 각각 POST /api/v2/transcribe에 한 번씩, 자막만, 타임스탬프 포함으로 요청하고 curl로 전송부터 전체 응답까지 시간을 쟀습니다. 크레딧은 각 응답이 알려 준 값입니다. 한 번씩만 측정했으니 시간은 예시로 봐 주세요.
파이썬에서 호출하기:
import requests
r = requests.post(
"https://www.youtubetranscript.dev/api/v2/transcribe",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"video": "aircAruvnKk", "mode": "auto", "format": {"timestamp": True}},
)
data = r.json()["data"]
for seg in data["transcript"]["segments"]:
print(seg["start"], seg["text"]) # start and end are in milliseconds
대신 비용이 듭니다. 라이브러리는 무료이고, API는 자막 있는 영상당 1크레딧이며 매달 10크레딧 무료, 유료 요금제는 500크레딧에 5달러부터입니다. "mode": "auto"로 하면 자막 없는 영상도 음성 2분당 1크레딧으로 변환합니다. 요청을 직접 작성하기 싫다면 파이썬 SDK가 있습니다.
제품에 음성 변환 API를 어떻게 연동하나요?
어떤 API든 같은 방식이 통합니다.
- 키는 서버에 둡니다. 사용자는 링크를 백엔드로 보내고 백엔드가 API를 호출합니다. 브라우저나 앱 코드에 키를 넣지 마세요.
- 모든 링크 형식을 받습니다. 사용자가 입력한 그대로 링크를 넘기세요. 저희 API는 전체 URL, youtu.be, Shorts, 임베드 링크, ID만 있는 경우를 모두 받습니다(전체 목록).
- 영상 ID별로 스크립트를 저장합니다. 대부분의 제품은 같은 인기 영상을 계속 요청합니다. 저희 API에서는 계정에 이미 있는 스크립트를 다시 받으면 위 표 셋째 줄처럼 무료지만, 로컬 사본이 더 빠릅니다.
- 자막 없는 영상은 작업으로 처리합니다. 음성 변환은 웹 요청이 기다리기에는 시간이 오래 걸립니다.
mode: "auto"와webhook_url을 함께 보내거나 돌아온 작업 ID를 폴링하고, 사용자에게는 진행 상태를 보여 주세요. - 많으면 배치를 씁니다. 재생목록, 채널, 밀린 작업은 단건 호출을 반복하지 말고 배치 엔드포인트를 써서 속도 제한을 넘지 않게 하세요.
모든 필드는 API 문서에 있고, 자막 없는 음성의 정확도와 비용은 음성 인식 API 가이드에서 측정했습니다.
무엇을 써야 하나요?
| 이런 경우라면 | 사용할 것 |
|---|---|
| 내 컴퓨터에서 스크립트로 영상 몇 개씩 처리 | youtube-transcript-api |
| 클라우드 서버, 서버리스 함수, 제품에 배포 | 호스팅 API, 또는 라이브러리와 순환형 주거용 프록시 |
| 자막 없는 영상 처리 | 음성을 변환하는 서비스 |
| 재생목록이나 채널 전체 가져오기 | 배치 엔드포인트가 있는 호스팅 API |
요약
- youtube-transcript-api는 무료, MIT 라이선스이며 간단합니다:
YouTubeTranscriptApi().fetch(video_id). - 클라우드 서버에서는 유튜브가 자주 차단합니다. 저희 클라우드 서버에서는 두 영상 모두 약 1.1초 만에
IpBlocked가 났습니다. 권장 해결책은 프록시입니다. - 이미 있는 자막만 읽으며, 연령 제한 영상은 현재 지원되지 않습니다.
- 호스팅 API는 같은 서버에서 같은 영상을 각각 4.2초, 1크레딧에 돌려줬고 자막 없는 영상도 처리합니다.
자주 묻는 질문
youtube-transcript-api란 무엇인가요?+
API 키나 브라우저 없이 유튜브에 이미 있는 영상 자막(자동 자막 포함)을 가져오는 오픈소스 파이썬 라이브러리(MIT 라이선스)입니다. pip install youtube-transcript-api로 설치하고 YouTubeTranscriptApi().fetch(video_id)로 호출합니다.
youtube-transcript-api에서 RequestBlocked나 IpBlocked가 나는 이유는?+
유튜브가 클라우드 업체 IP 주소에서 오는 요청 대부분을 차단하고, 요청이 너무 많은 IP도 막을 수 있기 때문입니다. 라이브러리 README가 직접 그렇게 설명하며 순환형 주거용 프록시를 권합니다. 2026년 11월 21일 저희 클라우드 서버에서는 테스트한 두 영상 모두 약 1.1초 만에 IpBlocked가 났습니다.
youtube-transcript-api로 자막 없는 영상을 변환할 수 있나요?+
아니요. 이미 있는 자막만 읽습니다. 자막이 꺼진 영상은 TranscriptsDisabled, 원하는 언어가 없는 영상은 NoTranscriptFound가 납니다. 음성에서 텍스트를 얻으려면 음성 인식 서비스가 필요합니다.
youtube-transcript-api는 무료인가요?+
네, 라이브러리는 무료이며 MIT 라이선스입니다. 다만 클라우드 IP가 차단되기 때문에 서버에서 쓰려면 보통 프록시 비용이 듭니다.
서버에서 youtube-transcript-api 대신 무엇을 쓸 수 있나요?+
가져오는 일을 대신해 주는 호스팅 스크립트 API입니다. 라이브러리가 차단된 바로 그 서버에서 YouTubeTranscript.dev API는 두 영상을 각각 4.2초, 1크레딧에 돌려줬고, 다시 요청했을 때는 1.3초에 무료였습니다.
제품에 음성 변환 API를 어떻게 연동하나요?+
API 키는 서버에 두고, 영상 링크를 하나의 엔드포인트로 보내고, 두 번 결제하지 않도록 영상 ID별로 스크립트를 저장하고, 자막 없는 영상은 웹훅이 있는 비동기 작업으로 처리하고, 영상이 많으면 배치 엔드포인트를 쓰세요.