Trascrizioni V2

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.

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

Specifica OpenAPI

Scarica lo YAML per importarlo in Postman o Insomnia, generare client o incollarlo in ChatGPT / Claude.

OpenAPI 3.0: V2 (consigliata)

Trascrivi un singolo video

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; falls back to ASR (async) when allow_asr is true and captions are unavailable.

POST/api/v2/transcribe

Parametri

videostringobbligatorio

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

Parametri

videostringobbligatorio

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}

Parametri

job_idpathobbligatorio

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).

Carica i tuoi file multimediali

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.

POST/api/v2/uploads

Parametri

filenamestringobbligatorio

Original filename. The extension is preserved for content sniffing.

mime_typestringobbligatorio

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

size_bytesintegerobbligatorio

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

duration_secintegerobbligatorio

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

Parametri

upload_idpathobbligatorio

Upload id returned by POST /uploads.

Trascrizione in batch

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.

POST/api/v2/batch

Parametri

video_idsstring[]obbligatorio

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}

Parametri

batch_idpathobbligatorio

Batch identifier returned from POST /batch.

Trascrizioni e job

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.

GET/api/v2/jobs

Parametri

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

Parametri

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}

Parametri

video_idpathobbligatorio

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

Parametri

video_idpathobbligatorio

YouTube 11-character video ID.

target_languageISO 639-1obbligatorio

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

Parametri

video_idpathobbligatorio

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}

Parametri

video_idpathobbligatorio

YouTube 11-character video ID.

languagequery

Only delete this language.

sourcequery

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

Playlist

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.

POST/api/v2/playlists/resolvePiani a pagamento

Parametri

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}

Parametri

playlist_idpathobbligatorio

Batch ID returned from /playlists/resolve.

List recent playlist batches for the authenticated user.

GET/api/v2/playlists/history

Canali

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.

POST/api/v2/channels/resolvePiani a pagamento

Parametri

channel_urlstringobbligatorio

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.

Rate limit

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}

Parametri

channel_idpathobbligatorio

Batch ID returned from /channels/resolve.

List recent channel batches for the authenticated user.

GET/api/v2/channels/history

Parametri

limitquery

Max items (default 50, max 100).

Integrazioni

SDK ufficiali, un server MCP per Claude e Cursor, un GPT personalizzato e template pronti per Make e n8n.

MCP serverClaude · Cursor

Repo

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.

Installa e configura

claude mcp add --transport http youtubetranscript https://mcp.youtubetranscript.dev --header "x-api-token: YOUR_API_KEY"

Node SDKnpm

npm

Tipi TypeScript di prima classe, retry, helper per la paginazione e verifica della firma dei webhook.

Installa e usa

npm install youtube-transcript-api

Python SDKPyPI

PyPI

Client sincroni e asincroni, type stub e helper per i flussi batch e webhook.

Installa e usa

pip install youtubetranscriptdevapi

Custom GPTChatGPT

Apri in ChatGPT

Aggiungi 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/*.

· Accesso OAuth: nessuna API key in chat
· Fallback ASR se mancano i sottotitoli
· Citazioni con timestamp e link alla fonte
· Prova gratuita su ogni account

Make.com & n8nNo-code

Sfoglia i template

Importa il template (o copia lo snippet) per aggiungere la trascrizione alle tue automazioni: Notion, Sheets, Slack, Airtable, flussi in stile Zapier.

Modulo 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 }
    }

Nodo HTTP n8n

{
  "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 / OpenAPIUn clic

Collection Postman

Importa la specifica OpenAPI in Postman, Insomnia o qualsiasi strumento che supporti OpenAPI 3.

Scarica YAML V2 Scarica JSON V2 Scarica YAML V1

Errori

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

Rate limit e quote

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

Supporto

Ti serve una mano? Scrivici: di solito rispondiamo entro poche ore.

Discord

@volods.taimi

support@youtubetranscript.dev

Status

Uptime e incidenti

POST/api/v2/transcribe

curl -X POST https://www.youtubetranscript.dev/api/v2/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video": "dQw4w9WgXcQ",
    "language": "en",
    "format": { "timestamp": true, "paragraphs": true }
  }'

200Risposta (200)

{
  "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
}

POST/api/v2/transcribe/estimate

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",
    "source": "asr",
    "asr_options": {
      "speakerLabels": true,
      "summarization": true,
      "translateTo": "es"
    }
  }'

200Risposta (200)

{
  "request_id": "req_abc123",
  "video_id": "dQw4w9WgXcQ",
  "source": "asr",
  "duration_seconds": 213,
  "duration_minutes": 4,
  "max_duration_minutes": 480,
  "exceeds_max_duration": false,
  "base_credits": 3,
  "addon_credits": 2,
  "estimated_credits": 5
}

GET/api/v2/jobs/{job_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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
}

GET/api/v2/jobs

curl "https://www.youtubetranscript.dev/api/v2/jobs?status=processing&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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 }
}

POST/api/v2/batch

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"],
    "source": "auto",
    "allow_asr": true,
    "webhook_url": "https://your-domain.com/webhook",
    "format": { "timestamp": true }
  }'

200Risposta (202)

{
  "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"
}

GET/api/v2/batch/{batch_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/batch/BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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"
}

GET/api/v2/transcripts

curl "https://www.youtubetranscript.dev/api/v2/transcripts?page=1&limit=50&status=succeeded" \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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 }
}

GET/api/v2/transcripts/{video_id}

curl "https://www.youtubetranscript.dev/api/v2/transcripts/dQw4w9WgXcQ?language=en" \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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" }]
  }
}

POST/api/v2/transcripts/{video_id}/translate

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" }'

200Risposta (200)

{
  "success": true,
  "message": "Translation completed",
  "language": "es",
  "credits_used": 4,
  "provider_used": "ai"
}

POST/api/v2/playlists/resolve

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 }'

200Risposta (200)

{
  "playlist_id": "PLxxxx",
  "title": "My playlist",
  "total": 42,
  "truncated": false,
  "items": [
    { "video_id": "dQw4w9WgXcQ", "title": "Example video" }
  ]
}

POST/api/v2/channels/resolve

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
  }'

200Risposta (200)

{
  "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
    }
  ]
}

GET/api/v2/channels/{channel_id}

curl -X GET https://www.youtubetranscript.dev/api/v2/channels/CHANNEL_BATCH_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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"
    }
  ]
}

GET/api/v2/channels/history

curl -X GET "https://www.youtubetranscript.dev/api/v2/channels/history?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

200Risposta (200)

{
  "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
}

RISORSE CORRELATE

Come estrarre le trascrizioniGuida passo passo per estrarre le trascrizioni di YouTube Elaborazione in bloccoElabora playlist e canali tramite l'API API per trascrizioni YouTubeEstrai trascrizioni in modo programmatico con la nostra REST API Template di automazioneWorkflow di partenza per Make.com e n8n con la V2 API Piani e prezziPiani Free, Basic, Pro e Business