YouTube스크립트API 가이드

API로 YouTube 자막(스크립트) 대량 다운로드하는 방법

공개 YouTube 동영상의 자막 텍스트를 대량으로 가져오고, 언어와 자막 누락을 처리하고, 검색·요약·RAG에 쓸 수 있도록 결과를 준비하는 실무 가이드입니다.

SocQ2026년 7월 19일 업데이트약 11분 소요

YouTube 스크립트 하나를 직접 내려받는 일은 쉽습니다. 하지만 공개 동영상 수백, 수천 개를 안정적으로 처리하는 워크플로를 만드는 것은 전혀 다른 문제입니다. 자막이 없는 동영상도 있고, 요청한 언어가 없을 수도 있고, 자동 생성 텍스트에 오류가 있을 수도 있으며, 모든 결과가 출처와 연결되어 있어야 합니다.

이 가이드에서는 SocQ YouTube Transcripts API로 제공되는 공개 YouTube 스크립트 텍스트를 가져오고, 여러 동영상 URL을 비동기 작업으로 처리하고, 정규화된 결과를 검색, 요약, 리서치, 검색 증강 생성(RAG)에 쓸 수 있게 준비하는 방법을 설명합니다.

빠른 답변: 공개 YouTube 동영상 URL과 선택 사항인 BCP-47 언어를 POST /v1/youtube/transcripts에 보내세요. 반환된 task_id를 저장하고, 작업 엔드포인트를 폴링한 다음, 완료된 레코드를 data.results.items에서 읽으면 됩니다. SocQ는 사용할 수 있는 공개 자막이 있을 때 일반 텍스트 스크립트와 동영상 정보를 반환합니다. 자막이 없는 경우에 새로 음성 인식(speech-to-text)을 수행하지는 않습니다.

공식 YouTube API로 공개 스크립트를 다운로드할 수 있나요?

아니요. 공식 YouTube Data API에는 자막 리소스가 있지만, 다운로드 메서드는 인증된 사용자가 관리할 수 있는 자막 트랙을 대상으로 설계되었습니다. Google의 현재 문서에 따르면 captions.download는 OAuth 인증이 필요하고 사용자에게 해당 동영상을 편집할 권한이 있어야 합니다. 이 메서드는 호출당 할당량도 200 유닛을 소모합니다.

채널을 소유하거나 관리하는 경우에는 문제없습니다. 하지만 임의의 공개 동영상에서 자막 텍스트를 내려받는 일반적인 방법은 아닙니다. 인증 요건은 Google의 공식 자막 다운로드 문서를 참고하세요.

세 가지 용도를 구분하면 도움이 됩니다.

요구 사항알맞은 방식
내 동영상의 자막 관리OAuth를 사용하는 YouTube Data API
선택한 공개 동영상에서 이미 제공되는 자막 텍스트 수집SocQ 같은 관리형 스크립트 엔드포인트
자막이 없을 때 오디오 전사별도의 speech-to-text 또는 ASR 파이프라인

SocQ는 두 번째 경우를 다룹니다. 제공되는 스크립트 텍스트를 가져올 뿐이며, 모든 공개 동영상에 스크립트가 있다고 주장하지 않고 새로 생성한 ASR 텍스트로 몰래 대체하지도 않습니다.

YouTube 스크립트 요청 보내기

이 엔드포인트는 공개 동영상 URL을 하나 이상 받습니다. en이나 zh-CN 같은 선호 언어도 함께 보낼 수 있습니다.

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://www.youtube.com/watch?v=arj7oStGLkU"
    ],
    "language": "en"
  }'

요청을 보내면 비동기 작업이 시작됩니다. 반환된 task_id를 저장하세요. 처리가 바로 끝나지 않는다고 같은 배치를 다시 제출해서는 안 됩니다.

작업이 최종 상태에 이를 때까지 폴링합니다.

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

queued와 running은 정상적인 중간 상태입니다. 작업이 성공하면 data.results.items를 읽습니다. 결과 페이지가 has_more: true를 알리면 반환된 next_cursor로 다음 페이지를 요청하세요.

스크립트 응답 구조 이해하기

정규화된 스크립트 레코드는 YouTube 페이지를 파싱하지 않고도 그대로 저장할 수 있는 안정적인 구조입니다.

{
  "id": "arj7oStGLkU",
  "platform": "youtube",
  "resource": "transcripts",
  "type": "transcript",
  "url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "text": "A plain-text transcript snapshot.",
  "language": "en",
  "available_languages": ["en"],
  "format": "plaintext",
  "transcript_source": "auto_generated",
  "author": {
    "id": "UCAuUUnT6oDeKwE6v1NGQxug",
    "username": "TED",
    "name": "TED",
    "url": "https://www.youtube.com/@TED"
  },
  "created_at": "2016-04-06T00:00:00",
  "collected_at": "2026-07-16T08:00:00Z",
  "extra": {
    "duration_seconds": 843
  }
}

후속 처리에서 가장 중요한 필드는 다음과 같습니다.

  • text: 선택된 일반 텍스트 스크립트.
  • language: 실제로 반환된 언어. 선호 언어와 다를 수 있습니다.
  • available_languages: 해당 동영상에서 확인된, 비어 있지 않은 스크립트 언어 목록.
  • transcript_source: 알려진 경우의 자막 출처 분류.
  • id, url, title, author: 추적을 위한 출처 정보.
  • created_at과 collected_at: 게시 시각과 수집 시각.
  • extra.duration_seconds: 품질 점검과 작업량 추정에 유용한 값.

응답은 의도적으로 일반 텍스트입니다. 신뢰할 수 있는 구간별 타임스탬프나 화자 라벨은 포함되지 않습니다. 정확한 인용 시각을 만들어 내거나, 타임스탬프 데이터가 있는 것처럼 응답을 SRT로 변환하지 마세요.

원하는 언어로 스크립트 가져오기

요청 언어는 보장이 아니라 선호입니다. 운영 워크플로에서는 항상 반환된 language를 기준으로 분기해야 합니다.

예를 들어 en을 요청하면 다음 중 하나가 될 수 있습니다.

  1. 영어 트랙이 선택될 수 있습니다.
  2. 호환되는 기본 언어 트랙이 선택될 수 있습니다.
  3. 다른 사용 가능한 트랙이 폴백으로 반환될 수 있습니다.
  4. 사용할 수 있는 공개 스크립트가 없으면 레코드가 생성되지 않을 수 있습니다.

모든 스크립트와 함께 language와 available_languages를 저장하세요. 정확한 언어 지원이 필수라면 폴백 결과를 번역, 검색, LLM에 바로 넘기지 말고 거부하거나 검토하세요.

transcript_source도 함께 보존하세요. 자동 생성 자막은 대규모 처리에서 가치가 있지만, YouTube는 음질이 나쁘거나, 지원되지 않는 언어이거나, 무음 구간이 길거나, 화자가 겹치거나, 여러 언어가 섞이면 자동 자막이 생성되지 않거나 품질이 떨어질 수 있다고 안내합니다. YouTube의 자동 자막 문제 해결 안내를 참고하세요.

YouTube 스크립트 대량 처리

대량 처리는 모든 URL이 성공한다고 가정하는 반복문이 아니라 데이터 파이프라인으로 설계해야 합니다.

Video URLs
   ↓
Validate and deduplicate
   ↓
Submit transcript batches
   ↓
Persist task IDs
   ↓
Poll with backoff
   ↓
Read every result page
   ↓
Validate language and source
   ↓
Store, chunk, index, or export

다음 방침을 따르세요.

  1. 제출 전에 URL을 정규화하세요. 중복된 watch, 공유, 임베드 URL을 같은 동영상 ID로 통합합니다.
  2. 배치를 복구할 수 있게 유지하세요. 각 배치와 입력 URL, 작업 ID, 제출 시각, 최종 상태를 저장합니다.
  3. 백오프를 두고 폴링하세요. 촘촘한 폴링 루프는 피하고, 작업이 queued나 running 상태로 남아 있는 동안 간격을 늘립니다.
  4. 부분 출력은 정상으로 간주하세요. 일부 동영상에 사용할 수 있는 자막이 없어서, 성공한 작업이라도 제출한 URL보다 레코드가 적을 수 있습니다.
  5. 끝까지 페이지네이션하세요. has_more가 false가 될 때까지 계속합니다.
  6. 쓰기를 멱등하게 만드세요. 재시도해도 중복이 생기지 않도록 동영상 ID와 스크립트 언어 기준으로 upsert합니다.
  7. 수집 시각을 기록하세요. 스크립트는 스냅샷이며, 자막은 나중에 수정되거나 삭제될 수 있습니다.

다음은 최소한의 Node.js 폴링 예시입니다.

const headers = {
  Authorization: `Bearer ${process.env.SOCQ_API_KEY}`,
  "Content-Type": "application/json"
};

const submitted = await fetch(
  "https://api.socq.ai/v1/youtube/transcripts",
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      urls: [
        "https://www.youtube.com/watch?v=arj7oStGLkU",
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      ],
      language: "en"
    })
  }
).then(response => response.json());

let task;
do {
  await new Promise(resolve => setTimeout(resolve, 3000));
  task = await fetch(
    `https://api.socq.ai/v1/tasks/${submitted.task_id}?limit=50`,
    { headers }
  ).then(response => response.json());
} while (["queued", "running"].includes(task.data.status));

if (task.data.status !== "succeeded") {
  throw new Error(`Transcript task ended with ${task.data.status}`);
}

const transcripts = task.data.results.items;

운영에 적용하기 전에 HTTP 상태 확인, 횟수 제한이 있는 재시도, 커서 페이지네이션, 구조화된 로깅, 취소 처리를 추가하세요.

자막 누락과 부분 결과 처리

결과가 없다고 해서 배치 전체가 실패한 것은 아닙니다. 흔한 원인은 다음과 같습니다.

  • 제작자가 자막을 제공하지 않았고 자동 자막도 없습니다.
  • 최근에 게시된 동영상이라 자막이 아직 처리 중입니다.
  • 음성 언어가 지원되지 않거나 인식되지 않았습니다.
  • 음질이 나쁘거나, 음성이 겹치거나, 동영상에 여러 언어가 섞여 있습니다.
  • 동영상이 비공개, 삭제, 제한 상태이거나 수집 환경에서 볼 수 없습니다.
  • 요청한 언어가 없고 사용할 수 있는 폴백도 없습니다.

실패는 끝없이 재시도하지 말고 유형별로 분류하세요.

실패 유형권장 조치
사용 가능한 자막 없음사용 불가로 표시하고, 필요하면 별도 ASR 워크플로로 전달
요청한 언어 없음available_languages를 확인하거나 통제된 폴백 허용
일시적인 작업 또는 네트워크 오류지수 백오프와 횟수 제한을 두고 재시도
비공개, 삭제, 제한된 동영상재시도를 중단하고 사유 기록
비어 있거나 의심스러운 스크립트검증을 위해 격리

출처를 밝히지 않고 ASR 출력을 YouTube 자막처럼 제시하지 마세요. 정확도 검토와 인용에서는 이 구분이 중요합니다.

스크립트 데이터를 안전하게 내보내기

일반 텍스트 결과는 TXT, JSON, CSV로 내보낼 수 있습니다.

TXT는 text 필드를 쓰고 메타데이터 레코드를 별도로 보관하세요. JSON은 정규화된 객체 전체를 보존하세요. CSV는 동영상당 한 행으로 id, url, title, language, transcript_source, text, collected_at 같은 필드를 사용하세요.

SRT와 VTT에는 시간 정보가 있는 구간이 필요합니다. SocQ 스크립트 엔드포인트는 구간이 아니라 일반 텍스트를 반환하므로, 이 응답만으로는 원본에 충실한 시간 정보 포함 자막 내보내기를 만들 수 없습니다.

검색 가능한 아카이브를 만든다면 스크립트 본문만 저장하지 마세요. 파생되는 모든 레코드에 동영상 ID, 정식 URL, 제목, 채널, 언어, 출처, 게시 시각, 수집 시각을 함께 보관하세요.

검색·RAG용으로 스크립트 준비하기

원본 스크립트는 대개 너무 길고 노이즈가 많아 모델에 한 덩어리로 보내기 어렵습니다. 더 나은 워크플로는 다음과 같습니다.

  1. 원문을 고치지 않고 공백만 정규화합니다.
  2. 비정상적으로 짧거나 빈 텍스트를 감지합니다.
  3. 텍스트를 일부가 겹치는 의미 단위 청크로 나눕니다.
  4. 모든 청크에 출처 메타데이터를 붙입니다.
  5. 임베딩을 생성합니다.
  6. 청크를 검색 또는 벡터 인덱스에 저장합니다.
  7. 모든 답변과 함께 동영상 URL과 스크립트 메타데이터를 반환합니다.

유용한 청크 레코드는 다음과 같은 모습입니다.

{
  "video_id": "arj7oStGLkU",
  "video_url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "language": "en",
  "transcript_source": "auto_generated",
  "chunk_index": 12,
  "text": "The transcript text for this chunk...",
  "collected_at": "2026-07-16T08:00:00Z"
}

원본 응답에는 구간 타임스탬프가 없으므로 정확한 시간 범위를 주장하지 말고 동영상을 인용하세요. 시간 단위의 인용이 꼭 필요하다면 검증된 구간을 제공하는 소스를 선택하거나 별도의 정렬 단계를 추가하세요.

스크립트를 가져오기 전에 알맞은 YouTube API 고르기

스크립트 수집은 더 큰 탐색 워크플로의 마지막 단계인 경우가 많습니다.

이렇게 하면 불필요한 스크립트 요청이 줄고, 최종 데이터셋이 명확한 탐색 기준에 연결됩니다.

스크립트 데이터셋을 최신 상태로 유지하기

스크립트 아카이브에는 명확한 갱신 정책이 있어야 합니다. 자막은 게시 후에 수정될 수 있고, 새 언어 트랙이 추가될 수 있으며, 이전에 제공되던 동영상이 삭제되거나 제한될 수도 있습니다. 매일 전부 다시 가져오는 것은 낭비이지만, 첫 응답을 영구적인 것으로 취급하면 검색 인덱스에 오래되었거나 출처를 추적할 수 없는 텍스트가 남을 수 있습니다.

용도에 따라 갱신 주기를 정하세요.

  • 일회성 리서치 데이터셋은 수집 시각을 저장하고, 분석에 필요하지 않다면 자동 갱신을 피하세요.
  • 검색 가능한 채널 아카이브는 자막이 게시 직후에 자주 수정되므로 최근 동영상을 더 자주 다시 확인하세요.
  • 컴플라이언스나 인용 워크플로에서는 인용문을 게시하거나 중대한 결정을 내리기 전에 출처를 다시 검증하세요.
  • 오래 운영하는 RAG 시스템은 콘텐츠 해시를 보관해서 바뀌지 않은 스크립트가 불필요한 재청킹과 임베딩 작업을 일으키지 않게 하세요.

갱신된 스크립트가 바뀌면 유일한 사본을 조용히 덮어쓰지 말고 새 버전을 만들거나 감사 기록을 남기세요. 최소한 동영상 ID, 스크립트 언어, 자막 출처, 수집 시각, 텍스트 해시, 파이프라인 버전을 저장하세요. 동영상에서 더 이상 결과가 나오지 않으면 기존 레코드를 마지막 확인 시점 기준 사용 불가로 표시하세요. 과거 스크립트가 처음부터 잘못되었다고 가정해서는 안 됩니다.

운영 체크리스트

대량 작업을 실행하기 전에 다음을 확인하세요.

  • 입력이 공개 YouTube 동영상 URL입니다.
  • URL이 정규화되고 중복이 제거되었습니다.
  • 작업 ID와 원본 입력이 저장되어 있습니다.
  • 폴링에 지연과 횟수 제한이 있는 재시도가 적용되어 있습니다.
  • 커서 페이지네이션이 has_more가 false가 될 때까지 계속됩니다.
  • 누락된 결과를 작업 실패와 별도로 다룹니다.
  • 반환된 언어를 검증합니다.
  • 자동 생성 자막에 라벨을 붙입니다.
  • 모든 청크와 내보내기에 출처 메타데이터가 유지됩니다.
  • 콘텐츠 이용이 관련 권리, 개인정보 기대 수준, 플랫폼 약관을 준수합니다.

자주 묻는 질문(FAQ)

공식 YouTube 스크립트 API가 있나요?

YouTube에는 공식 Captions API가 있지만, 자막 트랙을 다운로드하려면 OAuth와 동영상 편집 권한이 필요합니다. 임의의 공개 동영상을 위한 범용 스크립트 API는 아닙니다.

OAuth 없이 YouTube 스크립트를 다운로드할 수 있나요?

SocQ YouTube Transcripts API는 YouTube OAuth 승인이 아니라 SocQ API 키를 사용합니다. 선택한 공개 동영상 URL에서 제공되는 스크립트 텍스트를 가져옵니다.

자막이 없는 동영상의 스크립트를 SocQ가 생성해 주나요?

아니요. 이 엔드포인트는 제공되는 공개 스크립트 텍스트를 반환합니다. 사용할 수 있는 자막이 없는 동영상은 결과가 나오지 않을 수 있습니다. ASR 폴백이 필요하다면 별도로 명시한 speech-to-text 워크플로를 사용하세요.

특정 언어를 요청할 수 있나요?

네. en이나 zh-CN 같은 BCP-47 언어를 선택적으로 보낼 수 있지만, 실제로 반환되는 언어는 다를 수 있습니다. 항상 language와 available_languages를 확인하세요.

응답에 타임스탬프와 화자 라벨이 포함되나요?

아니요. 응답 형식은 정규화된 일반 텍스트이며 구간별 타임스탬프나 보장된 화자 라벨은 제공하지 않습니다.

한 번의 요청으로 여러 스크립트를 가져올 수 있나요?

네. urls에 공개 동영상 URL을 여러 개 담아 제출하고 작업 ID를 저장한 뒤, 비동기 작업이 성공하면 완료된 결과 페이지를 모두 읽으세요.

YouTube Transcripts API는 요금이 얼마인가요?

현재 엔드포인트 문서에는 정규화된 스크립트 결과당 0.5 크레딧으로 안내되어 있습니다. 요금은 바뀔 수 있으므로 운영 워크로드를 추정하기 전에 엔드포인트 페이지를 확인하세요.

YOUTUBE API

공개 YouTube URL로 워크플로를 테스트하세요

공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.

YouTube API 살펴보기