V2는 사용자가 소유하는 간소화된 스크립트 모델입니다. 빠른 캐시 적중과 일관된 응답을 우선하며, 언어를 요청하지 않는 한 예상치 못한 번역은 하지 않습니다.
https://www.youtubetranscript.dev/api/v2/transcribehttps://www.youtubetranscript.dev/api/v2/batchhttps://www.youtubetranscript.dev/api/v2/jobs/{job_id}https://www.youtubetranscript.dev/api/v2/batch/{batch_id}https://www.youtubetranscript.dev/api/v2/channels/resolvehttps://www.youtubetranscript.dev/api/v2/channels/{channel_id}https://www.youtubetranscript.dev/api/v2/channels/historyYAML을 다운로드해 Postman, Insomnia로 가져오거나, 클라이언트를 생성하거나, ChatGPT / Claude에 붙여 넣으세요.
동영상을 한 번에 하나씩 처리하는 가장 빠른 방법입니다. 자막 기반 스크립트는 몇 초 안에 반환되며, 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.
/api/v2/transcribevideostring필수YouTube URL or 11-character video ID. Required unless upload_id is set.
upload_idstringTranscribe 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-1Preferred transcript language (e.g. en). If unavailable, captions in another language may be returned: transcript.language reports the actual language.
sourceauto | manual | asrPreferred transcript source. Default: auto. Use asr for audio transcription (async, requires webhook_url).
allow_asrbooleanFall back to ASR if captions fail. Required for ASR-only videos.
formatobject{ timestamp, paragraphs, words }: include extra structure in the transcript.
webhook_urluriWhen set, the response returns processing and the result is delivered to your URL. Required for ASR.
asr_optionsobjectRich 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.
/api/v2/transcribe/estimatevideostring필수YouTube URL or 11-character video ID.
sourceauto | manual | asrDefaults to asr for cost preview.
asr_optionsobjectSame 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.
/api/v2/jobs/{job_id}job_idpath필수Identifier returned in the original transcribe response.
include_segmentsbooleanInclude segment-level timestamps in the transcript payload.
include_paragraphsbooleanInclude paragraph groupings.
include_wordsbooleanInclude 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.
/api/v2/uploadsfilenamestring필수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).
/api/v2/uploads/{upload_id}/completeupload_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.
/api/v2/batchvideo_idsstring[]필수Up to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.
languageISO 639-1Preferred language for every video.
sourceauto | manual | asrPreferred transcript source. Default: auto. source=asr requires webhook_url.
allow_asrbooleanFall back to ASR when captions fail. webhook_url is required.
formatobject{ timestamp, paragraphs, words }: applied to every result.
webhook_urluriDelivers the completed batch payload. Required when allow_asr=true or source=asr.
asr_optionsobjectRich 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.
/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.
/api/v2/jobspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
statusquerycompleted | processing | failed | requires_asr_confirmation.
List stored transcripts with search, status, language, and date filters. Metadata only (no full text) unless include_segments=true.
/api/v2/transcriptspagequeryPage number (default 1).
limitqueryItems per page (default 50, max 100).
searchqueryMatch video id, title, or transcript text.
statusqueryFilter by status; omit for succeeded.
languagequeryFilter by language code.
date_fromqueryISO date-time lower bound.
date_toqueryISO date-time upper bound.
include_segmentsqueryInclude 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.
/api/v2/transcripts/{video_id}video_idpath필수YouTube 11-character video ID.
idquerySpecific transcript/job id.
languagequeryPreferred language version.
sourcequeryauto | manual | asr.
include_timestampsqueryInclude 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.
/api/v2/transcripts/{video_id}/translatevideo_idpath필수YouTube 11-character video ID.
target_languageISO 639-1필수Language to translate into.
source_languageISO 639-1Source transcript language to translate from.
providerai | youtubeTranslation provider.
allow_ai_fallbackbooleanFall 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.
/api/v2/transcripts/{video_id}/languagesvideo_idpath필수YouTube 11-character video ID.
include_youtube_defaultqueryInclude 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.
/api/v2/transcripts/{video_id}video_idpath필수YouTube 11-character video ID.
languagequeryOnly delete this language.
sourcequeryOnly 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.
/api/v2/playlists/resolve유료 플랜playlist_urlstringPlaylist URL. One of playlist_url or playlist_id is required.
playlist_idstringPlaylist ID (the list= value).
limitintegerMax 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}.
/api/v2/playlists/{playlist_id}playlist_idpath필수Batch ID returned from /playlists/resolve.
List recent playlist batches for the authenticated user.
/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.
/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).
limitintegerMaximum 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.
/api/v2/channels/{channel_id}channel_idpath필수Batch ID returned from /channels/resolve.
List recent channel batches for the authenticated user.
/api/v2/channels/historylimitqueryMax items (default 50, max 100).
공식 SDK, Claude와 Cursor용 MCP 서버, 커스텀 GPT, 그리고 Make와 n8n용 기본 제공 템플릿을 제공합니다.
YouTube Transcript MCP 서버를 Claude Desktop, Cursor 또는 MCP 호환 클라이언트에 추가하세요. 동영상 스크립트 생성, 기존 스크립트 가져오기, 사용량 확인 도구가 추가됩니다.
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"완벽한 TypeScript 타입, 재시도, 페이지네이션 헬퍼, 웹훅 서명 검증을 지원합니다.
npm install youtube-transcript-api동기 및 비동기 클라이언트, 타입 스텁, 배치 및 웹훅 흐름용 헬퍼를 제공합니다.
pip install youtubetranscriptdevapi커스텀 GPT를 ChatGPT에 추가해 자연어로 YouTube 동영상을 요약, 인용, 번역하거나 질문하세요. 내부적으로 /api/v2/gpt/*를 사용합니다.
템플릿을 가져오거나 스니펫을 복사해 기존 자동화에 스크립트 생성을 추가하세요: Notion, Sheets, Slack, Airtable, Zapier 방식의 흐름 등.
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 }
}{
"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 }"
}
}OpenAPI 명세를 Postman, Insomnia 또는 OpenAPI 3을 지원하는 모든 도구로 가져오세요.
오류 발생 시 code와 message가 포함된 JSON 본문이 반환됩니다. HTTP 상태 코드는 오류 유형을 나타냅니다.
| HTTP 상태 | 오류 코드 | 설명 |
|---|---|---|
| 400 | invalid_request | Invalid JSON or missing required fields |
| 401 | invalid_api_key | Missing or invalid API key |
| 402 | payment_required | Insufficient credits |
| 404 | no_captions | No captions available and ASR not used |
| 429 | rate_limit_exceeded | Too many requests, check Retry-After |
| 500 | internal_error | Server error, retry with backoff |
플랜별 지속 요청 수와 배치 크기 상한입니다. 한도를 초과하는 버스트 요청에는 Retry-After 헤더와 함께 429가 반환됩니다.
| 플랜 | 요청 수 | 배치 크기 |
|---|---|---|
| Free | 1 req/s | 10 videos |
| Basic | 25 req/s | 500 videos |
| Pro | 50 req/s | 1,500 videos |
| Business | 100 req/s | 3,000 videos |
출시에 도움이 필요하신가요? 연락 주세요. 보통 몇 시간 안에 답변드립니다.