# FlashData YouTube Captions API

Recuperare le didascalie YouTube come testo timestamp e una trascrizione completa. Le didascalie fornite dal caricatore vengono selezionate per impostazione predefinita.

Riferimento canonico: https://flashdata.dev/it/docs/sources/youtube_captions
Recensito: 2026-10-23

Punto di arrivo: POST https://data.flashdata.dev/v1/queries/realtime
Autenticazione: X-API-Key: YOUR_API_KEY
Modalità: [Realtime](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md)

Permesso di origine richiesto: youtube_captions

Sostituisci YOUR_API_KEY con una chiave API che ha questo permesso di origine e crediti disponibili. Eseguire le richieste sul server o sul server host dell'agente.

[Impostare l'autenticazione](https://flashdata.dev/it/docs/guides/headers-and-authentication/reference.md)

[Recuperare le capzioni timestamp](https://flashdata.dev/it/docs/guides/timestamped-captions-recipe/reference.md)

<a id="quickstart"></a>

## Invia una richiesta

### Python

```bash
python3 -m pip install requests
```

```python
import json

import requests

api_key = "YOUR_API_KEY"
payload = {
    "source": "youtube_captions",
    "video_id": "dQw4w9WgXcQ",
    "params": {
        "language": "en",
        "auto": False,
    },
}

response = requests.post(
    "https://data.flashdata.dev/v1/queries/realtime",
    headers={"X-API-Key": api_key},
    json=payload,
    timeout=120,
)
response.raise_for_status()
print(json.dumps(response.json(), ensure_ascii=False, indent=2))
```

### Bash / cURL

```bash
api_key="YOUR_API_KEY"
curl --fail-with-body --max-time 120 --request POST "https://data.flashdata.dev/v1/queries/realtime" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $api_key" \
  --data-binary @- <<'FLASHDATA_JSON'
{
  "source": "youtube_captions",
  "video_id": "dQw4w9WgXcQ",
  "params": {
    "language": "en",
    "auto": false
  }
}
FLASHDATA_JSON
```

<a id="parameters"></a>

## Parametri

<a id="parameters-group-0"></a>

### Corpo della richiesta

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Sì | — | Impostare su youtube_captions.  |
| <a id="parameter-video_id"></a> video_id | string | Sì | Non impostato | Il video 11-character YouTube video ID, come FUfGcZ092b0. Accetta lettere, numeri, sottolineature e trattini. Lunghezza minima: 11. Lunghezza massima: 11. Modello: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | No | {} | Settings per questa richiesta.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | No | Non impostato | Async e solo lotto. Completamento HTTPS pubblico URL sulla porta 443, fino a caratteri 2,048. Nessuna credenziali utente o frammentazione URL. Omit, utilizzare null o una stringa vuota per nessuna notifica. In un lotto, impostare questo su ogni query, param esterni.  |

<a id="parameters-group-1"></a>

### Selezione di acquisizione

| Parametro | Tipologia | Obbligatorio | Predefinito | Designazione |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | No | en-orig → en | Omit per l'inglese (en-orig, poi en). Con auto=true, ogni codice prova prima la sua traccia -orig, poi il codice richiesto. Codici espliciti -orig e auto=false rimangono esatti. Arrays richiedono lingue distinte 1–10. Omettere di preferire en-orig e rientrare a en, tornando una traccia. Con auto=true, ogni codice prova prima la sua traccia -orig, poi il codice richiesto; codici espliciti -orig e auto=false rimangono esatti. Gli array di codici distinti 1–10 provano ogni lingua richiesta e restituiscono tracce e errori per lingua nell'ordine di richiesta. languageCode identifica la traccia selezionata; requestedLanguageCode è incluso quando differisce dal codice richiesto. |
| <a id="parameter-params-auto"></a> params.auto | boolean | No | false | true seleziona le didascalie generate da YouTube; false seleziona le didascalie fornite dal caricatore. Questo seleziona l'origine didascalia, non il rilevamento della lingua o la nuova trascrizione.  |

<a id="response"></a>

## Leggi il risultato

Salvare la risposta di successo JSON come response.json. Salvare questo come read-response.py ed eseguire pitone read-response.py. Utilizza solo la libreria standard di Python e non fa nuove richieste.

### read-response.py

```python
import json
from pathlib import Path

response = json.loads(Path("response.json").read_text(encoding="utf-8-sig"))
if response.get("status") not in ("done", "completed") or not isinstance(response.get("results"), list):
    raise SystemExit("Expected completed result JSON; inspect the response or job status.")
if not response["results"]:
    print("[]")
    raise SystemExit(0)
result = response["results"][0]

output = {
    "tracks": result.get("tracks", [result]),
    "errors": result.get("errors", []),
}
print(json.dumps(output, ensure_ascii=False, indent=2))
```

## Risposta di esempio

Esempio registrato; i campi e i conti dipendono dalla fonte e dall'ingresso richiesto.
```json
{
  "source": "youtube_captions",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 1.36,
          "end": 3.04,
          "text": "[♪♪♪]"
        },
        {
          "start": 18.64,
          "end": 21.880000000000003,
          "text": "♪ We're no strangers to love ♪"
        },
        {
          "start": 22.64,
          "end": 26.96,
          "text": "♪ You know the rules\nand so do I ♪"
        },
        {
          "start": 27.04,
          "end": 31.04,
          "text": "♪ A full commitment's\nwhat I'm thinking of ♪"
        },
        {
          "start": 31.12,
          "end": 35.08,
          "text": "♪ You wouldn't get this\nfrom any other guy ♪"
        },
        {
          "start": 35.16,
          "end": 39.52,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 40.52,
          "end": 42.92,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 43,
          "end": 45.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 45.2,
          "end": 47.080000000000005,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 47.32,
          "end": 51.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 51.48,
          "end": 53.48,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 53.6,
          "end": 55.52,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 55.72,
          "end": 59.36,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 60.8,
          "end": 64.8,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 64.88,
          "end": 69.03999999999999,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 69.12,
          "end": 72.96000000000001,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 73.36,
          "end": 77.2,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 77.4,
          "end": 82.04,
          "text": "♪ And if you ask me\nhow I'm feeling ♪"
        },
        {
          "start": 82.4,
          "end": 85.24000000000001,
          "text": "♪ Don't tell me\nyou're too blind to see ♪"
        },
        {
          "start": 85.32,
          "end": 87.27999999999999,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 87.36,
          "end": 89.32,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 89.44,
          "end": 93.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 93.8,
          "end": 95.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 95.76,
          "end": 98,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 98.08,
          "end": 102.04,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 102.2,
          "end": 104.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 104.28,
          "end": 106.36,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 106.48,
          "end": 110.08,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 110.76,
          "end": 112.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 112.8,
          "end": 114.68,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 114.96,
          "end": 118.76,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 119.84,
          "end": 122.96,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 123.72,
          "end": 127.36,
          "text": "♪ (Ooh, give you up) ♪"
        },
        {
          "start": 128.48,
          "end": 130.11999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 130.24,
          "end": 131.56,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 132.48,
          "end": 134.23999999999998,
          "text": "♪ Never gonna give,\nnever gonna give ♪"
        },
        {
          "start": 134.36,
          "end": 135.92000000000002,
          "text": "♪ (Give you up) ♪"
        },
        {
          "start": 136.76,
          "end": 141.07999999999998,
          "text": "♪ We've known each other\nfor so long ♪"
        },
        {
          "start": 141.2,
          "end": 145.2,
          "text": "♪ Your heart's been aching\nbut you're too shy to say it ♪"
        },
        {
          "start": 145.28,
          "end": 149.12,
          "text": "♪ Inside we both know\nwhat's been going ♪"
        },
        {
          "start": 149.52,
          "end": 153.20000000000002,
          "text": "♪ We know the game\nand we're gonna play it ♪"
        },
        {
          "start": 153.36,
          "end": 158.04000000000002,
          "text": "♪ I just wanna tell you\nhow I'm feeling ♪"
        },
        {
          "start": 158.64,
          "end": 161.32,
          "text": "♪ Gotta make you understand ♪"
        },
        {
          "start": 161.4,
          "end": 163.36,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 163.44,
          "end": 165.64,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 165.72,
          "end": 169.72,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 169.8,
          "end": 171.64,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 171.8,
          "end": 173.96,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 174.04,
          "end": 177.6,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 178.2,
          "end": 180.24,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 180.32,
          "end": 182.44,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 182.52,
          "end": 186.64,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 186.72,
          "end": 188.72,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 188.84,
          "end": 190.72,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 190.84,
          "end": 195.2,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        },
        {
          "start": 195.28,
          "end": 197.12,
          "text": "♪ Never gonna give you up ♪"
        },
        {
          "start": 197.2,
          "end": 199.24,
          "text": "♪ Never gonna let you down ♪"
        },
        {
          "start": 199.4,
          "end": 203.12,
          "text": "♪ Never gonna run around\nand desert you ♪"
        },
        {
          "start": 203.36,
          "end": 205.6,
          "text": "♪ Never gonna make you cry ♪"
        },
        {
          "start": 205.68,
          "end": 207.84,
          "text": "♪ Never gonna say goodbye ♪"
        },
        {
          "start": 207.92,
          "end": 211.32,
          "text": "♪ Never gonna tell a lie\nand hurt you ♪"
        }
      ],
      "fullText": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules\nand so do I ♪ ♪ A full commitment's\nwhat I'm thinking of ♪ ♪ You wouldn't get this\nfrom any other guy ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ And if you ask me\nhow I'm feeling ♪ ♪ Don't tell me\nyou're too blind to see ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ (Ooh, give you up) ♪ ♪ (Ooh, give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ Never gonna give,\nnever gonna give ♪ ♪ (Give you up) ♪ ♪ We've known each other\nfor so long ♪ ♪ Your heart's been aching\nbut you're too shy to say it ♪ ♪ Inside we both know\nwhat's been going ♪ ♪ We know the game\nand we're gonna play it ♪ ♪ I just wanna tell you\nhow I'm feeling ♪ ♪ Gotta make you understand ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪ ♪ Never gonna give you up ♪ ♪ Never gonna let you down ♪ ♪ Never gonna run around\nand desert you ♪ ♪ Never gonna make you cry ♪ ♪ Never gonna say goodbye ♪ ♪ Never gonna tell a lie\nand hurt you ♪"
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:46.290Z"
}
```

## Lingue multiple

Inviare un array di lingua per ricevere tracce e errori per lingua. Questo esempio mostra l'inglese disponibile e lo spagnolo non disponibile.

```json
{
  "source": "youtube_captions",
  "video_id": "jNQXAC9IVRw",
  "params": {
    "language": [
      "en",
      "es"
    ],
    "auto": false
  }
}
```

`results[0]`:

```json
{
  "videoId": "jNQXAC9IVRw",
  "isAutoGenerated": false,
  "tracks": [
    {
      "videoId": "jNQXAC9IVRw",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": false,
      "segments": [
        {
          "start": 0,
          "end": 1.5,
          "text": "Hello world."
        }
      ],
      "fullText": "Hello world."
    }
  ],
  "errors": [
    {
      "languageCode": "es",
      "code": "language_unavailable",
      "message": "Uploader-provided subtitles not available for language: es"
    }
  ]
}
```

## Campi di risposta

| Campo di applicazione | Tipologia | Designazione |
| --- | --- | --- |
| source | string | La fonte API richiesta. |
| status | string | fatto quando la richiesta in tempo reale riesce. |
| created_at | string | Tempo di creazione di risposta in formato ISO 8601. |
| usage.credits | number | Crediti a carico della richiesta, in base al tuo piano. |
| results[0].videoId | string | Il video richiesto ID. |
| results[0].languageCode | string | Codice traccia didascalia selezionato effettivo, come en-orig. |
| results[0].languageName | string · nullable | Nome della visualizzazione della lingua quando disponibile. |
| results[0].requestedLanguageCode | string · optional | Il codice richiesto quando differisce da languageCode, per esempio en quando en-orig è stato selezionato. |
| results[0].isAutoGenerated | boolean | Se le didascalie selezionate sono state generate automaticamente. |
| results[0].segments | array | Segmenti di cattura in ordine cronologico. |
| results[0].segments[].start | number | Tempo di inizio del segmento in pochi secondi. |
| results[0].segments[].end | number | Tempo di fine segmento in pochi secondi. |
| results[0].segments[].text | string | Testo di acquisizione. |
| results[0].fullText | string | Tutto il testo del segmento è entrato in una trascrizione. |
| results[0].tracks | array · optional | Solo per i sistemi linguistici. Le tracce disponibili in ordine di richiesta; ognuna ha i campi a binario singolo elencati sopra. |
| results[0].errors | array · optional | Solo per i sistemi linguistici. Lingue non richieste in ordine. Vuoto quando ogni traccia riesce. |
| results[0].errors[].languageCode | string | La lingua richiesta che ha fallito. |
| results[0].errors[].code | string | language_unavailable quando la traccia selezionata non esiste; retrieval_failed quando non può essere scaricata o analizzata. |
| results[0].errors[].message | string | Descrizione del guasto linguistico. |

- Lo API legge le didascalie già disponibili su YouTube. Non genera nuove trascrizioni o rientra tra le didascalie automatiche e provviste di caricabatterie.
- Un linguaggio di stringa mantiene la risposta single-track. Un array, anche ["en"], restituisce tracce ed errori invece di languageCode di alto livello, segmenti e fullText. Ogni traccia include quei campi. auto si applica a ogni lingua.
- Per gli elenchi di lingue, consulta errors per individuare le tracce non recuperate. Se non viene recuperata alcuna traccia, la richiesta non va a buon fine e i crediti riservati vengono rimborsati. Anche un errore di estrazione del video o la scadenza del tempo limite fanno fallire la richiesta.
- Disponibile in tempo reale, asincastro, lotto e massa. Le esportazioni di Bulk rimangono JSONL con un record per video, incluse le sue tracce e gli errori. Accept e X-Respond-With si applicano come al solito.

## Formati di risposta

Le risposte usano JSON per impostazione predefinita. Scegli un altro formato con queste intestazioni opzionali.

- Accept: application/json (predefinito) o text/plain. Testo normale presenta gli stessi campi in un layout leggibile e indentato.
- X-Respond-With: markdown. Lasciare unset per i campi originali. Markdown funziona con il formato di risposta.

Markdown è disponibile per domande in tempo reale e risultati completati.

I campi sottostanti descrivono la risposta predefinita JSON.

[Esempi di formato di richiesta e risposta](https://flashdata.dev/it/docs/guides/response-formats/reference.md#headers)

<a id="job-lifecycle"></a>

<a id="async-batch"></a>

## Nozioni di base sulle API

Il costruttore di richieste ed esempi sopra usano i parametri di questa fonte. Utilizzare gli esempi Python e cURL qui sotto per la presentazione condivisa, lo stato e i passaggi di risultato. Un corpo Batch è un oggetto JSON contenente query; ogni elemento restituisce il proprio lavoro ID.

- [Async richiesta e ricevuta](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#async)

<a id="job-status"></a>

- [Controllare lo stato del lavoro](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#status)

<a id="job-results"></a>

- [Recuperare i risultati completati](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#results)
- [richieste Batch JSON](https://flashdata.dev/it/docs/reference/batch-and-bulk/reference.md#batch)
- [API di elaborazione Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md)
- [Costruire un flusso di lavoro Bulk per questa sorgente](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md?source=youtube_captions#playground)
- [Clienti OpenAPI](https://flashdata.dev/docs/openapi.json)

<a id="webhooks"></a>

<a id="callbacks"></a>

## Notifiche di completamento

- [Ricevi e verifica il completamento webhooks](https://flashdata.dev/it/docs/guides/async-batch/reference.md#webhooks)

<a id="troubleshooting"></a>

## Risoluzione dei problemi

- [Errori e codici di stato](https://flashdata.dev/it/docs/errors/reference.md#status-codes)
- [Quando riprova](https://flashdata.dev/it/docs/errors/reference.md#retries)

## API correlate

- [YouTube Transcript API](https://flashdata.dev/it/docs/sources/youtube_transcript/reference.md)
- [YouTube Video Metadati API](https://flashdata.dev/it/docs/sources/youtube_metadata/reference.md)
