API 키

Transcripts V2

V2는 사용자가 소유하는 간소화된 스크립트 모델입니다. 빠른 캐시 적중과 일관된 응답을 우선하며, 언어를 요청하지 않는 한 예상치 못한 번역은 하지 않습니다.

POSThttps://www.youtubetranscript.dev/api/v2/transcribe
POSThttps://www.youtubetranscript.dev/api/v2/batch
GEThttps://www.youtubetranscript.dev/api/v2/jobs/{job_id}
GEThttps://www.youtubetranscript.dev/api/v2/batch/{batch_id}
POSThttps://www.youtubetranscript.dev/api/v2/channels/resolve
GEThttps://www.youtubetranscript.dev/api/v2/channels/{channel_id}
GEThttps://www.youtubetranscript.dev/api/v2/channels/history

OpenAPI 명세

YAML을 다운로드해 Postman, Insomnia로 가져오거나, 클라이언트를 생성하거나, ChatGPT / Claude에 붙여 넣으세요.

OpenAPI 3.0: V2 (권장)

단일 동영상 스크립트 생성

동영상을 한 번에 하나씩 처리하는 가장 빠른 방법입니다. 자막 기반 스크립트는 몇 초 안에 반환되며, ASR은 비동기로 실행되어 /api/v2/jobs/{job_id}로 폴링합니다.

Transcribe a single YouTube video. Returns immediately for caption-based videos; falls back to ASR (async) when allow_asr is true and captions are unavailable.

POST/api/v2/transcribe
파라미터
videostring필수

YouTube URL or 11-character video ID. Required unless upload_id is set.

upload_idstring

Transcribe an uploaded media file instead of a YouTube video (see /uploads). Forces the ASR path; webhook_url required. The upload id is returned as video_id in results.

languageISO 639-1

Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.

sourceauto | manual | asr

Preferred transcript source. Default: auto. Use asr for audio transcription (async, requires webhook_url).

allow_asrboolean

Fall back to ASR if captions fail. Required for ASR-only videos.

formatobject

{ timestamp, paragraphs, words }: include extra structure in the transcript.

webhook_urluri

When set, the response returns processing and the result is delivered to your URL. Required for ASR.

asr_optionsobject

Rich ASR config: language (+ codeSwitching, medicalMode, keyTerms), translateTo, speaker diarization (speakerLabels, speakerId + type/known values, multichannel, exact or min/max expected speakers), speech understanding (topics, summary, moderation, PII, profanity, sentiment), and formatting (punctuation, text formatting, filler words, custom date/phone/email patterns). Billable add-ons increase cost: preview with /transcribe/estimate. See the AsrOptions schema in the OpenAPI spec.

Dry-run credit estimate. Returns the ASR base cost plus any add-on surcharge for the requested asr_options without creating a job or charging credits.

POST/api/v2/transcribe/estimate
파라미터
videostring필수

YouTube URL or 11-character video ID.

sourceauto | manual | asr

Defaults to asr for cost preview.

asr_optionsobject

Same shape as /transcribe. Add-on charges are prorated by duration.

Poll a single transcription job. Use this for ASR jobs returned from /transcribe. Returns 202 while running and 200 when complete. Completed ASR jobs include asr_intelligence (summary, topics, sentiment, etc.) when those options were enabled.

GET/api/v2/jobs/{job_id}
파라미터
job_idpath필수

Identifier returned in the original transcribe response.

include_segmentsboolean

Include segment-level timestamps in the transcript payload.

include_paragraphsboolean

Include paragraph groupings.

include_wordsboolean

Include word-level timestamps (ASR only).

직접 미디어 업로드

보유한 오디오 또는 동영상 파일을 ASR 파이프라인으로 스크립트화합니다. 업로드 등록, 서명된 URL로 바이트 PUT, 업로드 완료의 세 단계를 거친 뒤 upload_id와 함께 /transcribe를 호출하세요. 결과는 웹훅으로 전달되며 다른 ASR 작업처럼 폴링할 수 있습니다.

Register an audio/video file upload and get a signed URL. PUT the raw file bytes to signed_url (with the file's Content-Type), finalize via /uploads/{upload_id}/complete, then transcribe with upload_id on /transcribe. Max 2GB and 8 hours per file.

POST/api/v2/uploads
파라미터
filenamestring필수

Original filename. The extension is preserved for content sniffing.

mime_typestring필수

Must start with audio/ or video/ (e.g. audio/mpeg, video/mp4).

size_bytesinteger필수

File size in bytes. Max 2147483648 (2GB).

duration_secinteger필수

Media duration in seconds. Max 28800 (8 hours). Used for the ASR credit estimate.

Finalize an upload after the PUT to signed_url succeeds. Verifies the file exists in storage and marks it ready. The upload can then be transcribed by passing upload_id to /transcribe (source="asr", webhook_url required).

POST/api/v2/uploads/{upload_id}/complete
파라미터
upload_idpath필수

Upload id returned by POST /uploads.

배치 스크립트 생성

한 번의 요청으로 여러 동영상의 스크립트를 생성한 뒤, 폴링하거나 웹훅으로 결과를 받으세요.

Submit up to 3,000 videos in one request. Returns within 2 seconds; poll the returned poll_url or wait for the webhook.

POST/api/v2/batch
파라미터
video_idsstring[]필수

Up to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.

languageISO 639-1

Preferred language for every video.

sourceauto | manual | asr

Preferred transcript source. Default: auto. source=asr requires webhook_url.

allow_asrboolean

Fall back to ASR when captions fail. webhook_url is required.

formatobject

{ timestamp, paragraphs, words }: applied to every result.

webhook_urluri

Delivers the completed batch payload. Required when allow_asr=true or source=asr.

asr_optionsobject

Rich ASR config applied to every video transcribed via ASR (same shape as /transcribe). Billable add-ons apply per video.

Check the status of a batch. Returns 202 while processing and 200 when results are ready. Stop polling once status is "completed", "partial", or "failed": finished batches never change, and re-fetching one more than 60 times in 24h returns 429 with a Retry-After header.

GET/api/v2/batch/{batch_id}
파라미터
batch_idpath필수

Batch identifier returned from POST /batch.

스크립트 및 작업

저장된 스크립트를 조회, 가져오기, 번역, 삭제하고 비동기 작업 목록을 확인합니다. 모든 엔드포인트는 동일한 API 키 인증을 사용합니다.

List your transcription jobs, newest first. Filter by status and paginate. Use the returned job_id with GET /api/v2/jobs/{job_id} to fetch a transcript.

GET/api/v2/jobs
파라미터
pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

statusquery

completed | processing | failed | requires_asr_confirmation.

List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.

GET/api/v2/transcripts
파라미터
pagequery

Page number (default 1).

limitquery

Items per page (default 50, max 100).

searchquery

Match video id, title, or transcript text.

statusquery

Filter by status; omit for succeeded.

languagequery

Filter by language code.

date_fromquery

ISO date-time lower bound.

date_toquery

ISO date-time upper bound.

include_segmentsquery

Include segments in each item.

Fetch the best owned transcript for a video, including asr_intelligence (summary, topics, sentiment, etc.), plus summary and mind_map when generated.

GET/api/v2/transcripts/{video_id}
파라미터
video_idpath필수

YouTube 11-character video ID.

idquery

Specific transcript/job id.

languagequery

Preferred language version.

sourcequery

auto | manual | asr.

include_timestampsquery

Include segments (default true).

Translate an owned transcript into a target language using YouTube captions or the AI provider. Returns free if you already own the translation.

POST/api/v2/transcripts/{video_id}/translate
파라미터
video_idpath필수

YouTube 11-character video ID.

target_languageISO 639-1필수

Language to translate into.

source_languageISO 639-1

Source transcript language to translate from.

providerai | youtube

Translation provider.

allow_ai_fallbackboolean

Fall back to AI when YouTube has no translation.

List the languages you already own for a video plus the YouTube translation targets available for it.

GET/api/v2/transcripts/{video_id}/languages
파라미터
video_idpath필수

YouTube 11-character video ID.

include_youtube_defaultquery

Include YouTube translation targets (default true).

Delete owned transcript(s) for a video. Optional language/source query params narrow the deletion; otherwise every language/source is removed. Also deletes bulk by id via POST /api/v2/transcripts/bulk-delete.

DELETE/api/v2/transcripts/{video_id}
파라미터
video_idpath필수

YouTube 11-character video ID.

languagequery

Only delete this language.

sourcequery

Only delete this source (auto | manual | asr).

재생목록

재생목록을 동영상 ID로 변환하고 /api/v2/batch로 스크립트를 생성한 뒤, 재생목록 배치와 기록을 확인하세요.

Resolve a YouTube playlist by URL or ID into its video list (metadata only). Pair the returned video_id values with /api/v2/batch to transcribe them.

POST/api/v2/playlists/resolve유료 플랜
파라미터
playlist_urlstring

Playlist URL. One of playlist_url or playlist_id is required.

playlist_idstring

Playlist ID (the list= value).

limitinteger

Max videos returned (1-100).

Fetch a playlist batch and per-video transcription job status. For overall batch progress, poll GET /api/v2/batch/{batch_id}.

GET/api/v2/playlists/{playlist_id}
파라미터
playlist_idpath필수

Batch ID returned from /playlists/resolve.

List recent playlist batches for the authenticated user.

GET/api/v2/playlists/history

채널

채널 스크립트 생성 흐름:1. POST /api/v2/channels/resolve: 채널의 업로드 동영상을 가져옵니다(동영상 메타데이터만).2. POST /api/v2/batch: 반환된 video_id 값을 보내 스크립트 생성을 시작합니다. 완료 시 결과를 받으려면 webhook_url을 사용하세요.3. GET /api/v2/batch/{batch_id}: 배치를 폴링해 전체 진행 상황과 집계 결과를 확인합니다.4. GET /api/v2/channels/{channel_id}: 동영상별 작업 상태가 포함된 채널 배치를 가져옵니다. /channels/history는 지난 채널 배치 목록을 반환합니다.

Fetch the uploads of a YouTube channel by URL, channel ID, or @handle. Returns video metadata only: pair the returned video_id values with /api/v2/batch to transcribe them.

POST/api/v2/channels/resolve유료 플랜
파라미터
channel_urlstring필수

YouTube channel URL, channel ID, or @handle. One of channel_url, channel_id, or handle must be provided. Handles are the public ID without the @ (for https://www.youtube.com/@jawed, the ID is jawed).

limitinteger

Maximum uploads returned. Defaults to the plan maximum.

Per-request cap: Basic 500 videos · Pro 1,500 videos · Business 3,000 videos. Monthly job cap: Basic 3 · Pro 8 · Business unlimited.

요청 한도

Plan-based: Free 1 req/s · Basic 25 req/s · Pro 50 req/s · Business 100 req/s. Exceeding the limit returns 429 with a Retry-After header.

Fetch a channel batch and the per-video transcription job status. For overall batch status (counts + progress), poll GET /api/v2/batch/{batch_id} instead: use this endpoint when you also need each video's individual job state.

GET/api/v2/channels/{channel_id}
파라미터
channel_idpath필수

Batch ID returned from /channels/resolve.

List recent channel batches for the authenticated user.

GET/api/v2/channels/history
파라미터
limitquery

Max items (default 50, max 100).

통합

공식 SDK, Claude와 Cursor용 MCP 서버, 커스텀 GPT, 그리고 Make와 n8n용 기본 제공 템플릿을 제공합니다.

MCP serverClaude · Cursor
저장소

YouTube Transcript MCP 서버를 Claude Desktop, Cursor 또는 MCP 호환 클라이언트에 추가하세요. 동영상 스크립트 생성, 기존 스크립트 가져오기, 사용량 확인 도구가 추가됩니다.

설치 및 구성
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"
Node SDKnpm
npm

완벽한 TypeScript 타입, 재시도, 페이지네이션 헬퍼, 웹훅 서명 검증을 지원합니다.

설치 및 사용
npm install youtube-transcript-api
Python SDKPyPI
PyPI

동기 및 비동기 클라이언트, 타입 스텁, 배치 및 웹훅 흐름용 헬퍼를 제공합니다.

설치 및 사용
pip install youtubetranscriptdevapi
Custom GPTChatGPT
ChatGPT에서 열기

커스텀 GPT를 ChatGPT에 추가해 자연어로 YouTube 동영상을 요약, 인용, 번역하거나 질문하세요. 내부적으로 /api/v2/gpt/*를 사용합니다.

  • · OAuth 로그인: 채팅에 API 키 불필요
  • · 자막이 없으면 ASR로 대체
  • · 타임스탬프와 출처 링크를 포함한 인용
  • · 모든 계정에 무료 체험 제공
Make.com & n8n노코드
템플릿 둘러보기

템플릿을 가져오거나 스니펫을 복사해 기존 자동화에 스크립트 생성을 추가하세요: Notion, Sheets, Slack, Airtable, Zapier 방식의 흐름 등.

Make.com 모듈
Module: HTTP > Make a request
- URL: https://www.youtubetranscript.dev/api/v2/transcribe
- Method: POST
- Headers:
    Authorization: Bearer {{connection.api_key}}
    Content-Type: application/json
- Body type: Raw / JSON
- Request content:
    {
      "video": "{{1.video_url}}",
      "format": { "timestamp": true }
    }
n8n HTTP 노드
{
  "name": "Transcribe Video",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://www.youtubetranscript.dev/api/v2/transcribe",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={ \"video\": $json.video_url }"
  }
}
Postman / OpenAPI원클릭
Postman 컬렉션

OpenAPI 명세를 Postman, Insomnia 또는 OpenAPI 3을 지원하는 모든 도구로 가져오세요.

오류

오류 발생 시 code와 message가 포함된 JSON 본문이 반환됩니다. HTTP 상태 코드는 오류 유형을 나타냅니다.

HTTP 상태오류 코드설명
400invalid_requestInvalid JSON or missing required fields
401invalid_api_keyMissing or invalid API key
402payment_requiredInsufficient credits
404no_captionsNo captions available and ASR not used
429rate_limit_exceededToo many requests, check Retry-After
500internal_errorServer error, retry with backoff

요청 한도 및 할당량

플랜별 지속 요청 수와 배치 크기 상한입니다. 한도를 초과하는 버스트 요청에는 Retry-After 헤더와 함께 429가 반환됩니다.

플랜요청 수배치 크기
Free1 req/s10 videos
Basic25 req/s500 videos
Pro50 req/s1,500 videos
Business100 req/s3,000 videos

지원

출시에 도움이 필요하신가요? 연락 주세요. 보통 몇 시간 안에 답변드립니다.

API 문서 - YouTube Transcript API