# FlashData YouTube Captions API

YouTube bijschriften ophalen als tekst met een tijdstempel en een volledig transcript. Uploader-ondertitels worden standaard geselecteerd.

Canonische referentie: https://flashdata.dev/nl/docs/sources/youtube_captions
Beoordeeld: 2026-10-23

Eindpunt: POST https://data.flashdata.dev/v1/queries/realtime
Authenticatie: X-API-Key: YOUR_API_KEY
Modi: [Realtime](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#realtime) · [Async](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#async) · [Batch](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md#batch) · [Bulk](https://flashdata.dev/nl/docs/reference/bulk-processing/reference.md)

Vereiste brontoestemming: youtube_captions

Vervang YOUR_API_KEY door een API sleutel met deze bronmachtiging en beschikbare credits. Verzoeken uitvoeren op uw server of agent host.

[Authenticatie instellen](https://flashdata.dev/nl/docs/guides/headers-and-authentication/reference.md)

[Tijdstempel bijschriften ophalen](https://flashdata.dev/nl/docs/guides/timestamped-captions-recipe/reference.md)

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

## Een verzoek versturen

### 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>

## Parameters

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

### Aanvraaginhoud

| Parameter | Type | Vereist | Standaard | Omschrijving |
| --- | --- | --- | --- | --- |
| <a id="parameter-source"></a> source | string | Ja | — | Instellen op youtube_captions.  |
| <a id="parameter-video_id"></a> video_id | string | Ja | Niet ingesteld | De 11-karakter YouTube video ID, zoals FUfGcZ092b0. Accepteert letters, cijfers, onderstrepingen en koppeltekens. Min lengte: 11. Maximale lengte: 11. Patroon: ^[A-Za-z0-9_-]{11}$ |
| <a id="parameter-params"></a> params | object | Nee | {} | Settings voor dit verzoek.  |
| <a id="parameter-callback_url"></a> callback_url | string · nullable | Nee | Niet ingesteld | Async en alleen batch. Publieke HTTPS voltooiing URL op poort 443, tot 2,048 tekens. Geen gebruikersgegevens of URL-fragment. Gebruik null of een lege tekenreeks zonder melding. In een batch, zet dit op elke query, buiten params.  |

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

### Bijschriftselectie

| Parameter | Type | Vereist | Standaard | Omschrijving |
| --- | --- | --- | --- | --- |
| <a id="parameter-params-language"></a> params.language | string \| array | Nee | en-orig → en | Omit for English (en-orig, dan en). Met auto=true probeert elke code eerst zijn -orig track, dan de gevraagde code. Expliciete -orig codes en auto=false blijven exact. Arrays-verzoek 1–10 verschillende talen. Geef de voorkeur aan en-orig en terugvallen op en, terug te keren een track. Met auto=true, elke code probeert eerst zijn -orig track, dan de gevraagde code; expliciete -orig codes en auto=false blijven exact. Arrays van 1–10 verschillende codes proberen elke gewenste taal en terugsturen tracks en per-taal fouten in aanvraag volgorde. languageCode identificeert de geselecteerde track; requestedLanguageCode is opgenomen wanneer het verschilt van de gevraagde code. |
| <a id="parameter-params-auto"></a> params.auto | boolean | Nee | false | true selecteert YouTube-gegenereerde ondertitels; false selecteert uploader-ondertitels. Dit selecteert bijschrift oorsprong, niet taaldetectie of nieuwe transcriptie.  |

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

## Lees het resultaat

Bewaar de succesvolle JSON respons als response.json. Sla dit op als read-response.py en voer python read-response.py uit. Het gebruikt alleen de standaardbibliotheek van Python en doet geen nieuw verzoek.

### 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))
```

## Voorbeeldantwoord

Opgenomen voorbeeld; velden en tellingen zijn afhankelijk van de bron en de gevraagde invoer.
```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"
}
```

## Meerdere talen

Stuur een taalreeks om tracks en per-taal fouten te ontvangen. Dit voorbeeld toont Engels beschikbaar en Spaans niet beschikbaar.

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

## Responsvelden

| Veld | Type | Omschrijving |
| --- | --- | --- |
| source | string | De gevraagde API bron. |
| status | string | gedaan wanneer het real-time verzoek slaagt. |
| created_at | string | Aanmaaktijd voor respons in ISO 8601-formaat. |
| usage.credits | number | Credits in rekening gebracht voor het verzoek, op basis van uw plan. |
| results[0].videoId | string | De gevraagde video ID. |
| results[0].languageCode | string | Werkelijk geselecteerde bijschrift track code, zoals en-orig. |
| results[0].languageName | string · nullable | Naam van de taalweergave indien beschikbaar. |
| results[0].requestedLanguageCode | string · optional | De gevraagde code als deze verschilt van languageCode, bijvoorbeeld en wanneer en-orig is geselecteerd. |
| results[0].isAutoGenerated | boolean | Of de geselecteerde bijschriften automatisch gegenereerd zijn. |
| results[0].segments | array | Bijschrift segmenten in chronologische volgorde. |
| results[0].segments[].start | number | Segment starttijd in seconden. |
| results[0].segments[].end | number | Segment eindtijd in seconden. |
| results[0].segments[].text | string | Bijschrift tekst. |
| results[0].fullText | string | Alle segmenttekst is samengevoegd in een transcriptie. |
| results[0].tracks | array · optional | Alleen voor taalarrays. Beschikbare tracks in aanvraagvolgorde; elk heeft de bovengenoemde single-track velden. |
| results[0].errors | array · optional | Alleen voor taalarrays. Foute talen in verzoekvolgorde. Leeg als elke track slaagt. |
| results[0].errors[].languageCode | string | De gewenste taal die faalde. |
| results[0].errors[].code | string | language_unavailable wanneer de geselecteerde track niet bestaat; retrieval_failed wanneer deze niet kon worden gedownload of ontleed. |
| results[0].errors[].message | string | Beschrijving van de taalfout. |

- De API leest bijschriften die al beschikbaar zijn op YouTube. Het genereert geen nieuwe transcripten of valt terug tussen automatische en uploader-onderschriften.
- Een string taal houdt de single-track response. Een array, zelfs ["en"], geeft tracks en fouten terug in plaats van top-level languageCode, segmenten en fullText. Elke track bevat die velden. auto is van toepassing op elke taal.
- Controleer bij taallijsten in errors welke ondertitelsporen zijn mislukt. Als geen enkel spoor wordt opgehaald, mislukt het verzoek en worden gereserveerde credits teruggegeven. Een fout bij het uitlezen van de video of het overschrijden van de tijdslimiet laat het verzoek ook mislukken.
- Beschikbaar voor real-time, async, batch en bulk. Bulk export blijft JSONL met één opname per video, inclusief tracks en fouten. Accept en X-Respond-With gelden zoals gewoonlijk.

## Antwoordformaten

Antwoorden gebruiken JSON standaard. Kies een ander formaat met deze optionele headers.

- Accept: application/json (standaard) of text/plain. Platte tekst geeft dezelfde velden weer in een leesbare, ingespringde lay-out.
- X-Respond-With: markdown. Laat uitgevallen voor originele velden. Markdown werkt met beide responsformaten.

Markdown is beschikbaar voor real-time queries en voltooide resultaten.

De velden hieronder beschrijven de standaard JSON response.

[Voorbeelden van verzoeken en antwoorden](https://flashdata.dev/nl/docs/guides/response-formats/reference.md#headers)

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

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

## API-basisprincipes

De aanvraagbouwer en voorbeelden hierboven gebruiken de parameters van deze bron. Gebruik hieronder de voorbeelden Python en cURL voor gedeelde inzending, status en resultaatstappen. Een Batch body is een JSON object met queries; elk item geeft zijn eigen job ID terug.

- [Async verzoek en ontvangst](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#async)

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

- [Taakstatus controleren](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#status)

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

- [Gereedgemaakte resultaten ophalen](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#results)
- [Batch JSON verzoeken](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md#batch)
- [API voor Bulk-verwerking](https://flashdata.dev/nl/docs/reference/bulk-processing/reference.md)
- [Bouw een Bulk workflow voor deze bron](https://flashdata.dev/nl/docs/reference/bulk-processing/reference.md?source=youtube_captions#playground)
- [Klant OpenAPI](https://flashdata.dev/docs/openapi.json)

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

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

## Aanmeldingen tot voltooiing

- [Ontvang en verifieer complete webhooks](https://flashdata.dev/nl/docs/guides/async-batch/reference.md#webhooks)

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

## Problemen oplossen

- [Fouten en statuscodes](https://flashdata.dev/nl/docs/errors/reference.md#status-codes)
- [Wanneer opnieuw proberen](https://flashdata.dev/nl/docs/errors/reference.md#retries)

## Gerelateerde API's

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