API 문서

YouTube 스크립트, 검색, 메타데이터를 위한 REST API입니다. 대시보드에서 API 키를 발급받으세요 — 무료 크레딧 100개, 카드 등록 불필요.

인증

API 키를 베어러 토큰으로 전달하거나 x-api-key 헤더를 사용하세요:

Authorization: Bearer sk_live_...
# or
x-api-key: sk_live_...

기본 URL

https://getyoutubetranscript.com/api/v1

크레딧 및 요금제

요금제가격월 크레딧충전 가격속도 제한
무료$0100개 (일회성)—분당 60회
월간월 $5.001,0001,000당 $2.50분당 200회
연간월 $4.50 (연 $54)1,0001,000당 $1.50분당 300회

1크레딧 = 성공한 요청 1건. 실패한 요청에는 요금이 부과되지 않습니다. 충전 크레딧은 구매일로부터 30일 또는 현재 결제 주기 종료 시점 중 늦은 시점에 만료되며, 사용하려면 활성 구독이 필요합니다.

엔드포인트

GET/transcript1크레딧

메타데이터(제목, 채널, 썸네일)와 함께 YouTube 동영상의 스크립트를 가져옵니다.

매개변수필수 여부설명
v예동영상 ID 또는 전체 YouTube URL
language아니오언어 코드 (기본값: en)

요청

curl "https://getyoutubetranscript.com/api/v1/transcript?v=jNQXAC9IVRw" \
  -H "Authorization: Bearer sk_live_..."

응답

{
  "success": true,
  "data": {
    "video_id": "jNQXAC9IVRw",
    "language_code": "en",
    "title": "Me at the zoo",
    "author_name": "jawed",
    "author_url": "https://www.youtube.com/channel/UC4Qob...",
    "thumbnail_url": "https://...",
    "transcript": "All right, so here we are...",
    "word_count": 39
  }
}
GET/search페이지당 1크레딧

필터와 페이지네이션을 사용해 YouTube 동영상을 검색합니다.

매개변수필수 여부설명
q예검색어 (최소 2자)
country아니오2자리 국가 코드 (기본값: us)
language아니오언어 코드 (기본값: en)
page_token아니오다음 페이지를 가져오기 위한 이전 응답의 pagination.next_page_token
limit아니오최대 결과 수 (기본값 20, 최대 50)

요청

curl "https://getyoutubetranscript.com/api/v1/search?q=lofi+beats" \
  -H "Authorization: Bearer sk_live_..."

응답

{
  "success": true,
  "data": {
    "query": "lofi beats",
    "video_results": [ { "title": "...", "videoId": "...", "channel": { "name": "..." } } ],
    "pagination": { "next_page_token": "..." }
  }
}
GET/resolve무료

채널 핸들, URL, 사용자 이름을 실제 채널 ID로 변환합니다. 이미 채널 ID이거나 ID를 포함한 URL 같은 구문적 입력은 네트워크 호출 없이 즉시 처리되며, 순수 핸들만 입력하면 실제 조회 1회가 발생합니다.

매개변수필수 여부설명
handle예채널 ID, URL, 또는 @핸들

요청

curl "https://getyoutubetranscript.com/api/v1/resolve?handle=@mkbhd" \
  -H "Authorization: Bearer sk_live_..."

응답

{
  "success": true,
  "data": {
    "channel_id": "UCBJycsmduvYEL83R_U4JriQ",
    "title": "Marques Brownlee",
    "handle": "http://www.youtube.com/@mkbhd",
    "resolved_via": "scrape"
  }
}
GET/playlist페이지당 1크레딧

재생목록의 동영상을 가져옵니다. 현재는 첫 페이지만 반환합니다 - has_more로 추가 동영상 존재 여부를 알 수 있지만, 추가 페이지 조회는 아직 지원되지 않습니다.

매개변수필수 여부설명
list예재생목록 ID 또는 URL

요청

curl "https://getyoutubetranscript.com/api/v1/playlist?list=PLxxx" \
  -H "Authorization: Bearer sk_live_..."

응답

{
  "success": true,
  "data": {
    "playlist_id": "PLxxx",
    "title": "...",
    "videos": [ { "position": 1, "id": "...", "title": "...", "channel": { "name": "..." } } ],
    "has_more": true
  }
}

오류

오류 발생 시 HTTP 상태 코드와 함께, 분기 처리에 사용할 수 있는 안정적인 code 필드가 포함된 JSON 본문이 반환됩니다:

상태코드의미
400BAD_REQUEST매개변수가 누락되었거나 잘못됨
401MISSING_API_KEY / INVALID_API_KEY키가 제공되지 않았거나, 키가 유효하지 않음/취소됨
402PAYMENT_REQUIRED크레딧 소진 - 충전하거나 업그레이드하세요
404VIDEO_UNAVAILABLE / TRANSCRIPT_NOT_FOUND동영상 또는 리소스를 찾을 수 없음
429RATE_LIMITED요금제 등급 대비 요청이 너무 많음
503UPSTREAM_UNAVAILABLE일시적인 상위 시스템 문제 - 재시도해도 안전함

출시 예정

채널 내부 검색, 채널의 전체 동영상 목록, 전체 재생목록 페이지네이션 기능을 개발 중입니다. RSS를 통한 신규 업로드 추적은 YouTube 측의 무관한 이슈로 인해 일시적으로 이용할 수 없습니다.

AI 도구와 함께 이 API 사용하기

요청을 직접 작성하는 대신 Claude(또는 다른 AI 코딩 도구)가 이 API를 호출하게 하고 싶으신가요? YouTube Transcript 스킬을 다운로드하세요 - 스크립트 가져오기, 검색 등의 방법을 학습시켜 주는 완성된 Claude 스킬입니다.