V2 è il modello di trascrizione semplificato e di proprietà dell'utente. Punta su cache hit rapidi, risposte coerenti e nessuna traduzione a sorpresa, a meno che tu non richieda una lingua.
https://www.youtubetranscript.dev/api/v2Incolla un link o un ID YouTube e ricevi la trascrizione, di solito in pochi secondi.
/transcribeInvia fino a 3.000 video in una richiesta e ricevi una notifica al termine.
/batchTrasforma una playlist o un canale nel suo elenco di video, pronto da trascrivere.
/playlists/resolveCarica un file e trascrivilo con il riconoscimento vocale.
/uploadsElenca, ottieni, traduci o elimina le tue trascrizioni.
/transcriptsControlla i job di riconoscimento vocale o ricevi un webhook al termine.
/jobs/{job_id}Novità: un solo parametro mode per ogni fonte di trascrizione
Scegli auto, captions_only, human_captions_only, speech_to_text_only invece di combinare source e allow_asr. Le richieste esistenti continuano a funzionare esattamente come prima. Scopri come funziona
Scarica lo YAML per importarlo in Postman o Insomnia, generare client o incollarlo in ChatGPT / Claude.
La via più rapida per un video alla volta. Le trascrizioni basate sui sottotitoli arrivano in pochi secondi; l'ASR gira in modo asincrono e si interroga tramite /api/v2/jobs/{job_id}.
Transcribe a single YouTube video. Returns immediately for caption-based videos. With mode=auto it falls back to ASR (async) when captions are unavailable: you get status processing and a job_id to poll at /api/v2/jobs/{job_id}, or the result is POSTed to webhook_url if you set one. Responses include the mode the request ran with.
/api/v2/transcribevideostringobbligatorioYouTube 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 (mode must be omitted or speech_to_text_only); webhook_url required. The upload id is returned as video_id in results.
modeauto | captions_only | human_captions_only | speech_to_text_onlyWhere the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). When omitted, your account default from the API Dashboard applies: auto for accounts created from October 2026, captions_only for older accounts unless changed. ASR modes work without webhook_url: poll the returned job_id.
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 | asrLegacy, still supported: use mode instead. Default: auto. asr transcribes the audio (async, requires webhook_url).
allow_asrbooleanLegacy, still supported: use mode=auto instead. Falls back to ASR if captions fail.
formatobject{ timestamp, paragraphs, words }: include extra structure in the transcript.
webhook_urluriWhen set, ASR results are POSTed to your URL. Optional with mode (poll the job_id instead); required for legacy source=asr. Ignored by captions_only and human_captions_only, which never use 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.
curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video": "dQw4w9WgXcQ",
"mode": "auto",
"language": "en",
"format": { "timestamp": true, "paragraphs": true }
}'{
"request_id": "req_abc123",
"status": "completed",
"data": {
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"transcript": {
"text": "Welcome to this tutorial...",
"language": "en",
"source": "auto",
"segments": [
{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }
]
}
},
"credits_used": 1,
"mode": "auto"
}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/estimatevideostringobbligatorioYouTube URL or 11-character video ID.
modeauto | captions_only | human_captions_only | speech_to_text_onlySame values as /transcribe. Use speech_to_text_only (or auto) to preview the ASR cost.
sourceauto | manual | asrLegacy, still supported: use mode instead. Defaults to asr for cost preview.
asr_optionsobjectSame shape as /transcribe. Add-on charges are prorated by duration.
curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe/estimate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video": "dQw4w9WgXcQ",
"mode": "speech_to_text_only",
"asr_options": {
"speakerLabels": true,
"summarization": true,
"translateTo": "es"
}
}'{
"request_id": "req_abc123",
"video_id": "dQw4w9WgXcQ",
"source": "asr",
"mode": "speech_to_text_only",
"duration_seconds": 213,
"duration_minutes": 4,
"max_duration_minutes": 480,
"exceeds_max_duration": false,
"base_credits": 3,
"addon_credits": 2,
"estimated_credits": 5
}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_idpathobbligatorioIdentifier 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).
curl -X GET https://www.youtubetranscript.dev/api/v2/jobs/JOB_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "req_abc123",
"status": "completed",
"data": {
"video_id": "dQw4w9WgXcQ",
"transcript": {
"text": "Welcome to this tutorial...",
"language": "en",
"source": "asr",
"segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }]
}
},
"credits_used": 6
}Trascrivi i tuoi file audio o video tramite la pipeline ASR. Tre passaggi: registra l'upload, invia i byte con PUT all'URL firmato, finalizza: poi chiama /transcribe con upload_id. I risultati arrivano al tuo webhook e si interrogano come qualsiasi job 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/uploadsfilenamestringobbligatorioOriginal filename. The extension is preserved for content sniffing.
mime_typestringobbligatorioMust start with audio/ or video/ (e.g. audio/mpeg, video/mp4).
size_bytesintegerobbligatorioFile size in bytes. Max 2147483648 (2GB).
duration_secintegerobbligatorioMedia duration in seconds. Max 28800 (8 hours). Used for the ASR credit estimate.
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filename": "interview.mp3",
"mime_type": "audio/mpeg",
"size_bytes": 48211234,
"duration_sec": 1820
}'
# Then PUT the raw file bytes to the returned signed_url:
curl -X PUT "SIGNED_URL_FROM_RESPONSE" \
-H "Content-Type: audio/mpeg" \
--data-binary @interview.mp3
# Then finalize:
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/UPLOAD_ID/complete \
-H "Authorization: Bearer YOUR_API_KEY"{
"upload_id": "up_a1B2c3D4",
"bucket": "asr-media",
"path": "user-uuid/up_a1B2c3D4/interview.mp3",
"token": "eyJhbGciOiJIUzI1NiJ9...",
"signed_url": "https://api.youtubetranscript.dev/storage/v1/object/upload/sign/asr-media/...?token=..."
}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_idpathobbligatorioUpload id returned by POST /uploads.
curl -X POST https://www.youtubetranscript.dev/api/v2/uploads/up_a1B2c3D4/complete \
-H "Authorization: Bearer YOUR_API_KEY"{
"upload_id": "up_a1B2c3D4",
"status": "uploaded",
"filename": "interview.mp3",
"duration_sec": 1820
}Trascrivi molti video con una sola richiesta, poi interroga lo stato o ricevi i risultati via webhook.
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[]obbligatorioUp to 3,000 IDs depending on plan. Free = 10, Basic = 500, Pro = 1,500, Business = 3,000.
languageISO 639-1Preferred language for every video.
modeauto | captions_only | human_captions_only | speech_to_text_onlyWhere the transcript comes from (recommended). auto: captions first, speech-to-text (ASR) only if the video has none. captions_only: any captions, never ASR. human_captions_only: human-made captions only. speech_to_text_only: always transcribe the audio. auto and speech_to_text_only can charge ASR credits. Replaces source + allow_asr; cannot be combined with them. Note: mode=auto is not the same as legacy source=auto (captions only, which is mode=captions_only). For batch, auto and speech_to_text_only require webhook_url. When omitted, your API Dashboard default applies (an ASR default only when webhook_url is set).
sourceauto | manual | asrLegacy, still supported: use mode instead. Default: auto. source=asr requires webhook_url.
allow_asrbooleanLegacy, still supported: use mode=auto instead. webhook_url is required.
formatobject{ timestamp, paragraphs, words }: applied to every result.
webhook_urluriDelivers the completed batch payload. Required for mode=auto or speech_to_text_only (legacy: 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.
curl -X POST https://www.youtubetranscript.dev/api/v2/batch \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_ids": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
"mode": "auto",
"webhook_url": "https://your-domain.com/webhook",
"format": { "timestamp": true }
}'{
"batch_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"results": [],
"summary": { "total": 2, "succeeded": 0, "failed": 0, "processing": 2 },
"poll_url": "https://www.youtubetranscript.dev/api/v2/batch/550e8400-e29b-41d4-a716-446655440000",
"created_at": "2026-05-15T10:00:00Z"
}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_idpathobbligatorioBatch identifier returned from POST /batch.
curl -X GET https://www.youtubetranscript.dev/api/v2/batch/BATCH_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"batch_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"summary": { "total": 2, "succeeded": 2, "failed": 0, "processing": 0 },
"results": [
{ "request_id": "req_1", "status": "completed", "data": { "video_id": "dQw4w9WgXcQ" } },
{ "request_id": "req_2", "status": "completed", "data": { "video_id": "jNQXAC9IVRw" } }
],
"credits_used": 2,
"webhook_delivered": true,
"completed_at": "2026-05-15T10:04:00Z"
}Elenca, recupera, traduci ed elimina le trascrizioni salvate, ed elenca i job asincroni. Tutti gli endpoint accettano la stessa autenticazione con API key.
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.
curl "https://www.youtubetranscript.dev/api/v2/jobs?status=processing&limit=25" \
-H "Authorization: Bearer YOUR_API_KEY"{
"jobs": [
{
"job_id": "9c2...",
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"language": "en",
"source": "asr",
"status": "processing",
"error": null,
"credits_used": 0,
"created_at": "2026-07-06T12:00:00Z",
"started_at": "2026-07-06T12:00:01Z",
"completed_at": null
}
],
"count": 1,
"pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasMore": false }
}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.
curl "https://www.youtubetranscript.dev/api/v2/transcripts?page=1&limit=50&status=succeeded" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{
"id": "b1f...",
"video_id": "dQw4w9WgXcQ",
"video_title": "Example video",
"language": "en",
"source_kind": "auto",
"status": "succeeded",
"created_at": "2026-07-06T12:00:00Z",
"word_count": 1234,
"segment_count": 88,
"credits_used": 1
}
],
"count": 1,
"pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasMore": false }
}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_idpathobbligatorioYouTube 11-character video ID.
idquerySpecific transcript/job id.
languagequeryPreferred language version.
sourcequeryauto | manual | asr.
include_timestampsqueryInclude segments (default true).
curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ?language=en" \
-H "Authorization: Bearer YOUR_API_KEY"{
"id": "b1f...",
"video_id": "dQw4w9WgXcQ",
"language": "en",
"text": "Welcome to this tutorial...",
"segments": [{ "text": "Welcome to this tutorial.", "start": 0, "end": 2500 }],
"has_timestamps": true,
"source_kind": "asr",
"video_title": "Example video",
"summary": null,
"mind_map": null,
"asr_intelligence": {
"summary": "A short overview of the video...",
"topics": [{ "text": "Technology", "relevance": 0.92 }],
"sentiment": [{ "text": "Great tutorial", "sentiment": "POSITIVE" }]
}
}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_idpathobbligatorioYouTube 11-character video ID.
target_languageISO 639-1obbligatorioLanguage 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.
curl -X POST "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/translate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "target_language": "es", "provider": "ai" }'{
"success": true,
"message": "Translation completed",
"language": "es",
"credits_used": 4,
"provider_used": "ai"
}List the languages you already own for a video plus the YouTube translation targets available for it.
/api/v2/transcripts/{video_id}/languagesvideo_idpathobbligatorioYouTube 11-character video ID.
include_youtube_defaultqueryInclude YouTube translation targets (default true).
curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ/languages" \
-H "Authorization: Bearer YOUR_API_KEY"{
"video_id": "dQw4w9WgXcQ",
"languages": ["en", "es"],
"youtube_translation_languages": ["fr", "de", "ja"]
}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_idpathobbligatorioYouTube 11-character video ID.
languagequeryOnly delete this language.
sourcequeryOnly delete this source (auto | manual | asr).
curl -X DELETE "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ" \
-H "Authorization: Bearer YOUR_API_KEY"{
"success": true,
"deleted": 2,
"message": "Successfully deleted 2 transcripts"
}Risolvi una playlist in ID video, trascrivili con /api/v2/batch, poi consulta il batch della playlist e la cronologia.
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/resolvePiani a pagamentoplaylist_urlstringPlaylist URL. One of playlist_url or playlist_id is required.
playlist_idstringPlaylist ID (the list= value).
limitintegerMax videos returned (1-100).
curl -X POST https://www.youtubetranscript.dev/api/v2/playlists/resolve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "playlist_url": "https://www.youtube.com/playlist?list=PLxxxx", "limit": 100 }'{
"playlist_id": "PLxxxx",
"title": "My playlist",
"total": 42,
"truncated": false,
"items": [
{ "video_id": "dQw4w9WgXcQ", "title": "Example video" }
]
}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_idpathobbligatorioBatch ID returned from /playlists/resolve.
curl "https://www.youtubetranscript.dev/api/v2/playlists/{playlist_batch_id}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"playlist": { "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist" },
"videos": [
{ "video_id": "dQw4w9WgXcQ", "video_title": "Example video", "status": "succeeded" }
]
}List recent playlist batches for the authenticated user.
/api/v2/playlists/historycurl "https://www.youtubetranscript.dev/api/v2/playlists/history" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{ "id": "3f1...", "playlist_id": "PLxxxx", "title": "My playlist", "total_videos": 42 }
],
"count": 1
}Flusso di trascrizione di un canale:1. POST /api/v2/channels/resolve: recupera i video caricati dal canale (solo metadati).2. POST /api/v2/batch: invia i valori video_id restituiti per avviare la trascrizione. Usa un webhook_url per ricevere i risultati al termine.3. GET /api/v2/batch/{batch_id}: interroga il batch per l'avanzamento complessivo e i risultati aggregati.4. GET /api/v2/channels/{channel_id}: recupera un batch del canale con lo stato dei job per ogni video; /channels/history elenca i batch dei canali precedenti.
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/resolvePiani a pagamentochannel_urlstringobbligatorioYouTube 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.
curl -X POST https://www.youtubetranscript.dev/api/v2/channels/resolve \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"handle": "@youtube",
"limit": 50
}'{
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"subscriber_count": 42000000,
"video_count": 1200,
"total": 1,
"truncated": false,
"items": [
{
"video_id": "dQw4w9WgXcQ",
"title": "Latest upload",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"published_at": "2026-05-01T12:00:00Z",
"duration_seconds": 420
}
]
}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_idpathobbligatorioBatch ID returned from /channels/resolve.
curl -X GET https://www.youtubetranscript.dev/api/v2/channels/CHANNEL_BATCH_ID \
-H "Authorization: Bearer YOUR_API_KEY"{
"channel": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"total_videos": 2,
"completed_count": 1,
"failed_count": 0,
"status": "processing",
"created_at": "2026-05-15T10:00:00Z"
},
"videos": [
{
"id": "job_123",
"video_id": "dQw4w9WgXcQ",
"video_title": "Latest upload",
"status": "succeeded",
"created_at": "2026-05-15T10:00:00Z",
"finished_at": "2026-05-15T10:00:10Z"
}
]
}List recent channel batches for the authenticated user.
/api/v2/channels/historylimitqueryMax items (default 50, max 100).
curl -X GET "https://www.youtubetranscript.dev/api/v2/channels/history?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"{
"history": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"channel_id": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
"channel_title": "YouTube",
"total_videos": 25,
"completed_count": 25,
"failed_count": 0,
"status": "completed",
"created_at": "2026-05-15T10:00:00Z",
"completed_at": "2026-05-15T10:12:00Z"
}
],
"count": 1
}Cerca, poi trascrivi:1. GET /api/v2/search/videos (/shorts, /channels, /playlists): trova contenuti per parola chiave. 1 credito per richiesta.2. Invia l'url di un video a POST /api/v2/transcribe, oppure l'url di un canale o di una playlist a /api/v2/channels/resolve o /api/v2/playlists/resolve.3. Passa next_page_token come page_token per ottenere altri risultati (1 credito per pagina).
Search YouTube videos by keyword. Live streams are included with type "live". Pass a result's url to /api/v2/transcribe to get its transcript. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/videosqqueryobbligatorioSearch text, up to 200 characters.
durationqueryVideo length: under_3_min, 3_to_20_min or over_20_min.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
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.
curl "https://www.youtubetranscript.dev/api/v2/search/videos?q=python%20tutorial&duration=over_20_min" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "6f1c2a9e-4b7d-4f2a-9c1e-2d3b4a5c6d7e",
"type": "videos",
"query": "python tutorial",
"results": [
{
"type": "video",
"video_id": "kqtD5dpn9C8",
"url": "https://www.youtube.com/watch?v=kqtD5dpn9C8",
"title": "Python for Beginners - Learn Coding with Python in 1 Hour",
"thumbnail": "https://i.ytimg.com/vi/kqtD5dpn9C8/hq720.jpg",
"channel": {
"channel_id": "UCWv7vMbMWH4-V0ZXdmDpPBA",
"title": "Programming with Mosh",
"handle": "programmingwithmosh",
"url": "https://www.youtube.com/@programmingwithmosh",
"thumbnail": "https://yt3.ggpht.com/..."
},
"view_count": 25574982,
"view_count_text": "25,574,982 views",
"published_at": null,
"published_text": "6 years ago",
"duration_seconds": 3606,
"duration_text": "1:00:06",
"badges": []
}
],
"next_page_token": "cDA6RWdJUUFV...",
"credits_used": 1,
"credits_remaining": 4602
}Search YouTube Shorts by keyword. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/shortsqqueryobbligatorioSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
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.
curl "https://www.youtubetranscript.dev/api/v2/search/shorts?q=python%20tips" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "0b8e7d6c-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"type": "shorts",
"query": "python tips",
"results": [
{
"type": "short",
"video_id": "gbYLsUngzLc",
"url": "https://www.youtube.com/watch?v=gbYLsUngzLc",
"title": "Top 10 Most Important Python Functions You Must Know!",
"thumbnail": "https://i.ytimg.com/vi/gbYLsUngzLc/oar2.jpg",
"channel": null,
"view_count": 1200000,
"view_count_text": "1.2M views",
"published_at": null,
"published_text": null,
"duration_seconds": null,
"duration_text": null,
"badges": []
}
],
"next_page_token": "cDA6RWdJUUNR...",
"credits_used": 1,
"credits_remaining": 4601
}Search YouTube channels by keyword. Pass a result's url to /api/v2/channels/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/channelsqqueryobbligatorioSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
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.
curl "https://www.youtubetranscript.dev/api/v2/search/channels?q=python" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"type": "channels",
"query": "python",
"results": [
{
"type": "channel",
"channel_id": "UCKQdc0-Targ4nDIAUrlfKiA",
"url": "https://www.youtube.com/@PythonSimplified",
"title": "Python Simplified",
"handle": "PythonSimplified",
"description": "Hi everyone! My name is Mariya and I'm a software developer...",
"thumbnail": "https://yt3.googleusercontent.com/...",
"subscriber_count": 286000,
"subscriber_count_text": "286K",
"badges": ["Verified"]
}
],
"next_page_token": "cDA6RWdJUUFn...",
"credits_used": 1,
"credits_remaining": 4600
}Search YouTube playlists by keyword. Pass a result's url to /api/v2/playlists/resolve to list its videos. 1 credit per request, including each next page. Refunded if the search fails.
/api/v2/search/playlistsqqueryobbligatorioSearch text, up to 200 characters.
upload_datequeryOnly results uploaded within: today, this_week, this_month or this_year.
sort_byqueryrelevance (default) or popular.
regionqueryTwo-letter country code to localize results, e.g. US.
page_tokenqueryThe next_page_token from a previous response, to get the next page. null means there are no more results.
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.
curl "https://www.youtubetranscript.dev/api/v2/search/playlists?q=python%20course" \
-H "Authorization: Bearer YOUR_API_KEY"{
"request_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"type": "playlists",
"query": "python course",
"results": [
{
"type": "playlist",
"playlist_id": "PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
"url": "https://www.youtube.com/playlist?list=PLsyeobzWxl7omDoEYrrf3oXvXxa6MPgek",
"title": "Python Tutorial | Complete Python Course (Beginner to Advanced)",
"thumbnail": "https://i.ytimg.com/vi/YZkyL-f-YXY/hq720.jpg",
"video_count": 54,
"first_video_id": "YZkyL-f-YXY",
"channel": {
"channel_id": "UC59K-uG2A5ogwIrHw4bmlEg",
"title": "Telusko",
"handle": "Telusko",
"url": "https://www.youtube.com/@Telusko",
"thumbnail": null
}
}
],
"next_page_token": "cDA6RWdJUUF3...",
"credits_used": 1,
"credits_remaining": 4599
}SDK ufficiali, un server MCP per Claude e Cursor, un GPT personalizzato e template pronti per Make e n8n.
Aggiungi il server MCP di YouTube Transcript a Claude Desktop, Cursor o qualsiasi client compatibile con MCP. Offre strumenti per trascrivere video, recuperare trascrizioni esistenti e controllare l'utilizzo.
claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"Tipi TypeScript di prima classe, retry, helper per la paginazione e verifica della firma dei webhook.
npm install youtube-transcript-apiClient sincroni e asincroni, type stub e helper per i flussi batch e webhook.
pip install youtubetranscriptdevapiAggiungi il nostro GPT personalizzato a ChatGPT per riassumere, citare, tradurre o interrogare qualsiasi video di YouTube in linguaggio naturale. Sotto il cofano usa /api/v2/gpt/*.
Importa il template (o copia lo snippet) per aggiungere la trascrizione alle tue automazioni: Notion, Sheets, Slack, Airtable, flussi in stile 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 }"
}
}Importa la specifica OpenAPI in Postman, Insomnia o qualsiasi strumento che supporti OpenAPI 3.
Gli errori restituiscono un body JSON con code e message. Lo stato HTTP indica la categoria.
| Stato HTTP | Codice di errore | Descrizione |
|---|---|---|
| 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 |
Limiti per piano su richieste continue e dimensioni dei batch. Superando il limite ricevi un 429 con header Retry-After.
| Piano | Richieste | Dimensione batch |
|---|---|---|
| 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 |
Ti serve una mano? Scrivici: di solito rispondiamo entro poche ore.