Een YouTube-transcript ophalen vanuit je code
Stuur de videolink met je API-sleutel naar POST /v1/transcriptions. Dat kan vanuit Python of elke andere HTTP-client. Met wait=60 wacht de verbinding maximaal 60 seconden. Bekijk de requestvelden en statuscodes voordat je begint.
Maak een API-sleutel in het dashboard en gebruik die vanuit je server of script. Bewaar meteen het ID dat je terugkrijgt. Is het transcript nog niet klaar wanneer het request terugkomt? De verwerking loopt door. Lees de status met GET /v1/transcriptions/:id in plaats van dezelfde video opnieuw in te sturen.
Houd in je app rekening met queued, fetching en transcribing. Pas bij completed is er tekst om te tonen. Bij failed handel je de fout af. Een trage verbinding of onbereikbare video is geen geslaagde transcriptie met een leeg tekstveld.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'Met transcript_source weet je wat je terugkrijgt
De response vermeldt of de tekst uit ondertitels komt en of de maker die heeft geüpload of YouTube ze heeft gegenereerd. billed_minutes is de videoduur, naar boven afgerond. Alle velden staan bij het transcriptieobject.
Bewaar transcript_source en caption_kind als de herkomst voor je app belangrijk is. Ondertitels van de maker behouden hun gepubliceerde tekst, zonder tijdstempels per woord. Automatische YouTube-ondertitels hebben begintijden per woord. Speech-to-text geeft begin- en eindtijden, met een confidence-waarde. Het JSON-voorbeeld laat de structuur zien; de tekst is geen citaat uit de voorbeeldvideo.
Naast de volledige tekst krijg je segmenten met begin- en eindtijden in seconden. Daarmee koppel je notities aan de speler of geef je een assistent precies de juiste passage. Voeg alleen include=words toe aan een JSON-request als je ook de extra gegevens per woord nodig hebt.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}Ondertitels ophalen of de audio transcriberen?
source staat standaard op auto. Met captions vraag je uitsluitend om ondertitels: zijn die niet bruikbaar, dan krijg je no_captions en betaal je niets. Met stt laat je altijd de audio transcriberen. Lees ook hoe taal en sprekerherkenning de bronkeuze beïnvloeden.
Kies captions (alleen ondertitels) als je juist de gepubliceerde track nodig hebt. Kies speech-to-text voor een nieuwe transcriptie of sprekerherkenning. Met source=auto en diarize=true slaan we de ondertitels over. captions combineren met diarize=true kan niet: het request wordt afgewezen, de sprekeroptie verdwijnt niet stilzwijgend.
De ondertiteltrack moet passen bij de gevraagde taal. Met language=auto gebruiken we de oorspronkelijke taal van de video. Automatisch vertaalde tracks vallen af. Bij speech-to-text is language een herkenningshint, geen opdracht om de tekst te vertalen.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}Lees eerst de fout, stuur niet meteen opnieuw
Een privévideo, leeftijdsbeperking of lopende livestream vraagt om een andere bron, niet om steeds hetzelfde request. Bij no_captions beslis je of een audiotranscript ook bruikbaar is. Loopt de verwerking nog? Lees dan hetzelfde ID opnieuw. De foutcodes helpen je bepalen wat je client moet doen.
Moet je een create-request na een verbindingsfout herhalen, gebruik dan het Idempotency-Key-contract. Een eerdere transcriptie hergebruiken is een aparte optie: video én instellingen moeten overeenkomen. Een gecachet transcript kan nog steeds als nieuwe taak tellen. Een bestaande, afgeronde transcriptie opnieuw lezen kost geen minuten.
Bouw je voor meerdere platforms, kijk dan per bron wat kan. YouTube, X, TikTok en Bluesky kunnen bijvoorbeeld ondertitels leveren, met speech-to-text als alternatief in auto. Hetzelfde endpoint accepteert ook TikTok-video’s en Instagram-video’s. Gebruik de bronnenmatrix voor je invoercontrole, zodat je geen ongeldige combinatie van opties aanbiedt.