curl로 30초 만에 YouTube 스크립트 추출하기

터미널에서 YouTube 스크립트를 텍스트로 가져오는 모습

YouTube 영상을 일반 텍스트로 변환하는 데 계정도, SDK도, 헤드리스 브라우저도 필요 없습니다. youtube2text.org는 REST API입니다. 키를 받는 호출 한 번, 스크립트를 가져오는 호출 한 번이면 끝입니다.

1단계: 무료 데모 키 받기

curl -s https://youtube2text.org/api/demo-key

응답:

{"success": true, "apiKey": "yt_..."}

데모 키는 공용이며 IP 단위로 제한됩니다(IP당 월 5개 영상). 간단히 테스트해 보거나 가끔 스크립트를 돌리기에 딱 좋습니다.

2단계: 스크립트 가져오기

curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID&maxChars=5000" \
  -H "x-api-key: yt_YOUR_KEY"

성공 응답:

{"result": {"videoId": "...", "title": "...", "pubDate": "2025-01-01T00:00:00-07:00",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

이게 전부입니다. 알아 두면 좋은 세부 사항 몇 가지:

url은 YouTube의 모든 형식을 받습니다 — watch?v=, youtu.be, embed, 또는 11자리 영상 ID 그 자체.
maxChars는 스크립트를 잘라냅니다(기본값이자 최대값: 150000). 토큰 예산이 정해진 LLM에 텍스트를 넣을 때 유용합니다.
x-api-key 대신 Authorization: Bearer <key>를 사용해도 됩니다.
POST를 선호한다면? 같은 엔드포인트로 JSON을 보내세요: {"url": "...", "maxChars": 5000}.

오류 처리

모든 오류는 동일한 기계 판독 가능 형식으로 반환됩니다:

{"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "...", "status": 429,
           "docsUrl": "https://youtube2text.org/api.md", "retryAfterSeconds": 3600}}

실제로 만나게 될 코드들:

TRANSCRIPT_UNAVAILABLE — 영상에 자막이 전혀 없는 경우.
RATE_LIMIT_EXCEEDED — 할당량 소진; retryAfterSeconds가 재시도 시점을 알려줍니다.
UNAUTHORIZED — 키가 없거나 유효하지 않은 경우; /api/demo-key에서 새로 받으세요.

데모 키로는 부족할 때

youtube2text.org/app/keys에서 Google 계정으로 로그인하고 자신만의 키를 만드세요. 무료 계정도 월 5개 영상을 제공하며, 유료 플랜은 월 50개부터 무제한까지 있습니다.

파라미터, 모든 오류 코드, MCP 연동까지 담은 완전한 기계 판독 가능 레퍼런스는 youtube2text.org/api.md에 있습니다. 셸 스크립트가 아니라 AI 에이전트에 연결하려는 경우라면 다음으로 MCP 가이드를 읽어 보세요.