API로 YouTube 스크립트 가져오기 (curl, Python, JavaScript)

API로 YouTube 스크립트를 가져오려면 영상 URL이나 ID와 API 키를 담아 HTTP 요청을 한 번 보내고, 응답에서 스크립트를 읽으면 됩니다. 이 가이드는 sum.video 스크립트 API로 curl, Python, JavaScript 요청을 보여 주고, 이어서 형식, 오류, 비용을 다룹니다.

API가 반환하는 것

이 엔드포인트는 공개 YouTube 영상의 기존 자막을 반환합니다. 제작자가 직접 쓴 자막이든 YouTube가 자동 생성한 자막이든 상관없습니다. 오디오를 받아 적지는 않습니다. 영상에 자막이 없으면 추측하는 대신 오류가 반환됩니다(자세한 내용은 아래).

기본 사항은 다음과 같습니다.

• 엔드포인트: POST https://sum.video/api/v1/transcript (GET도 가능)
• 인증: 키를 X-API-Key 헤더에 넣거나 Authorization: Bearer <key>로 전달
• 입력: url 또는 video_id
• 선택 사항 lang (기본값 en)
• 선택 사항 format: json, text, srt

응답에는 자막 트랙의 실제 언어와 자동 생성 여부도 들어 있어서, 어느 정도의 품질을 기대할지 알 수 있습니다.

1단계: API 키 만들기

로그인한 뒤 API 대시보드(sum.video의 /dashboard/api)에서 키를 만드세요. 활성 키는 최대 5개까지 둘 수 있어서 스테이징용과 운영용을 나눌 때 편리합니다. 첫 키에는 무료 크레딧 10개(스크립트 5건)가 들어 있으니 아래 내용을 모두 무료로 시험해 볼 수 있습니다.

2단계: 첫 요청 보내기

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

GET도 되기 때문에 URL만 만드는 스크립트에서도 시험할 수 있습니다. 키는 로그에 남지 않도록 헤더로 전달하는 편이 좋습니다.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18 이상 또는 브라우저)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

키는 서버에 보관하세요. 브라우저 코드에 넣은 키는 개발자 도구를 여는 누구나 복사할 수 있습니다.

3단계: 알맞은 형식 고르기

영상의 특정 순간으로 링크하려면 json을 쓰고, 세그먼트의 offset으로 링크를 만드세요. LLM에 넣을 때는 text가 더 작고 단순합니다. 나중에 스크립트 안을 직접 검색하고 싶다면 YouTube 영상 스크립트 안에서 검색하는 방법을 보세요.

4단계: 언어 고르기

lang의 기본값은 en입니다. de나 es처럼 원하는 언어로 설정하세요. 응답에는 실제로 반환된 트랙의 언어가 표시되니, 짐작하지 말고 확인하세요. 영상에는 자막 트랙이 하나뿐인 경우가 많고, API는 실제 자막을 반환하므로 번역은 해 주지 않습니다.

5단계: 오류 처리하기

처음부터 다음 경우를 염두에 두세요.

• 404 no_transcript: 영상에 자막이 없거나, 라이브 방송, 비공개 영상, 삭제된 영상입니다. 다시 시도해도 소용없습니다. 건너뛰거나 사용자에게 다른 영상을 요청하세요.
• 402 budget_exceeded: 설정한 월간 크레딧 한도에 도달했습니다. 다음 섹션을 보세요.
• 속도 제한: 키 하나당 분당 60건까지 허용됩니다. 일괄 작업은 간격을 두고, 제한에 걸리면 속도를 늦추세요.
• 우리 쪽 장애: 잠시 뒤 다시 시도하세요. 비용은 들지 않습니다.

서버 오류에서는 재시도하고 404에서는 건너뛰는 단순한 반복문이면 운영에 필요한 대부분을 처리할 수 있습니다.

비용

스크립트 한 건에는 2크레딧이 듭니다. 스크립트를 반환하지 않았거나 sum.video 쪽에서 실패한 요청은 비용이 들지 않으므로, 404가 잔액을 깎는 일은 없습니다. 잔액은 GET /api/v1/credits로 확인할 수 있습니다.

크레딧은 만료되지 않는 일회성 팩으로 판매됩니다.

Pro 구독자는 매달 보너스 크레딧 100개도 받습니다. 채널 전체를 가져오는 것처럼 더 무거운 작업은 자동 충전과 예산을 다루는 시나리오 대규모 RAG 앱을 위한 YouTube 스크립트를 읽어 보세요. 요금제도 참고하세요.

만들기 전에 알아야 할 한계

• 자막이 있는 영상만 동작합니다. 404 no_transcript의 가장 큰 이유입니다.
• 자동 생성 자막에는 특히 이름, 억양, 전문 용어에서 오류가 있을 수 있습니다.
• API는 스크립트만 반환하고 요약은 하지 않습니다. 스크립트 위에 요약, 타임스탬프, 채팅이 필요하다면 YouTube 요약기가 해 주며, 스크립트 도구는 영상 하나를 위한 코드 없는 버전입니다.
• 공식 YouTube Data API는 여기서 대안이 되지 못합니다. 자막 다운로드 메서드는 영상을 편집할 권한이 있어야 하므로 본인 영상용입니다(Google 문서).

출처

• YouTube Data API: Captions.download
• sum.video 스크립트 API