YouTube Transcripts
YouTube 스크립트는 공개 동영상에서 이용 가능한 자막을 일반 텍스트로 변환한 것으로, 언어, 자막 출처, 채널 컨텍스트, 게시 정보, 재생 시간을 함께 담고 있습니다. 이 텍스트는 접근성, 검색, 인용 검토, 주제 분석, 요약, 콘텐츠 색인에 활용할 수 있습니다.
YouTube Transcripts API 주요 기능
- 여러 동영상 스크립트 조회한 번의 요청으로 여러 공개 동영상 URL에서 이용 가능한 스크립트 텍스트를 가져옵니다.
- 선호 언어 선택en, zh-CN처럼 유효한 BCP-47 코드로 선호 언어를 요청합니다.
- 언어 제공 현황 메타데이터실제로 선택된 언어와 이용 가능한 스크립트 언어 목록을 반환합니다.
- 일반 텍스트 스크립트 형식일관된 일반 텍스트 형식으로 제공하며, 알려진 경우 스크립트 출처 정보도 함께 제공합니다.
- 추적 가능한 동영상 컨텍스트모든 스크립트를 동영상 ID, 제목, 채널 정보, 게시일, 재생 시간, collected_at과 연결합니다.
YouTube Transcripts API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
urls | 필수 | 공개 YouTube 동영상 URL로, 쉼표 또는 줄바꿈으로 구분합니다. |
language | 선택 | 선택적으로 지정하는 BCP-47 형식의 선호 자막 언어(예: en, zh-CN)입니다. 반환되는 언어는 다를 수 있습니다. |
YouTube Transcripts API 사용 방법
중요한 동영상을 먼저 고른 다음에 자막을 요청하세요. 그리고 텍스트를 검색, RAG, 요약, 번역, 컴플라이언스 워크플로에 넣기 전에 반환된 언어와 출처를 확인합니다.
- 공개 동영상 URL을 고릅니다. 탐색이나 메타데이터 검토로 관련 없는 항목을 먼저 걸러내는 것이 좋습니다.
- urls와 선택 항목인 BCP-47 language를 /v1/youtube/transcripts로 POST하고 task_id를 저장합니다.
- /v1/tasks/{task_id}를 폴링합니다. 배치가 성공해도 결과가 제출한 URL 수보다 적을 수 있습니다.
- 항목마다 language, available_languages, transcript_source를 확인한 뒤 일반 텍스트를 청크로 나누고, has_more가 true인 동안 페이지네이션합니다.
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"}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50YouTube Transcripts API 추천 활용 사례
- 동영상 요약: 이용 가능한 스크립트 텍스트로 긴 동영상의 요약, 조사 노트, 콘텐츠 브리프를 만듭니다.
- 검색 가능한 동영상 아카이브: 스크립트 텍스트를 동영상 ID, 제목, 채널 정보, 언어 메타데이터와 함께 색인합니다.
- 주제·정보 추출: 선택한 공개 동영상 모음 전체에서 주제, 개체, 주장, 키워드를 식별합니다.
- 번역·현지화: 선택된 언어와 이용 가능한 언어 필드를 활용해 스크립트 텍스트를 번역 워크플로로 보냅니다.
YouTube Transcripts API 활용 팁
- 항상 요청한 선호 언어가 아니라 반환된 language를 기준으로 분기하세요. 폴백으로 다른 이용 가능한 트랙이 선택되는 것은 정상 동작입니다.
- 자동 생성 자막에는 이름, 문장 부호, 전문 용어 오류가 있을 수 있습니다. transcript_source를 보관하고, 중요한 발췌문은 동영상과 대조해 검토하세요.
- 작업이 성공했는데 항목이 더 적다면, 대개 일부 동영상에 사용할 수 있는 공개 자막이 없었다는 뜻이며 자동으로 배치 실패가 되는 것은 아닙니다.
- 일반 텍스트에는 구간 타임스탬프나 화자 라벨이 없습니다. 이 응답으로 정확한 인용 시점을 만들어 내지 마세요.
- 이후 단계에서 텍스트를 청크로 나누더라도, 인용을 추적할 수 있도록 모든 청크에 동영상 ID, 언어, 출처, collected_at을 유지하세요.
- 스크립트를 검색 가능한 카탈로그에 노출할 때는 Videos로 제목, 미디어, 공개 지표를 보강하세요.
- 정확한 언어 지원이 필수라면 먼저 available_languages를 비교하고, 폴백 결과는 검토가 필요한 예외로 다루세요.
관련 API
YouTube Transcripts API 외에 YouTube의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- YouTube Channel Videos API — 채널 URL에서 쇼츠와 라이브 방송을 제외한 일반 공개 동영상을 수집합니다.
- YouTube Comments API — 공개 댓글, 작성자, 참여도, 원본 동영상, 대화 맥락을 수집합니다.
- YouTube Channels API — 공개 채널 정보, 이미지, 인증 여부, 공개된 오디언스 통계를 가져옵니다.
- YouTube Videos API — 알고 있는 동영상 또는 쇼츠 URL의 메타데이터, 썸네일, 길이, 참여도를 가져옵니다.
- YouTube Shorts API — 채널별로 공개 쇼츠, 썸네일, 길이, 게시 정보, 참여도를 수집합니다.
- YouTube Channel Live Videos API — 채널의 라이브 영역에 노출된 공개 방송 기록을 수집하며, 출처 맥락과 공개된 지표를 포함합니다.
- YouTube Search API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Hashtag Search API
- YouTube Playlist Videos API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Channel Search API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API