REST API-referentie

Gebruik https://api.transcript1.com/v1 als basis-URL voor je requests.

• Je verstuurt en ontvangt JSON, met veldnamen in snake_case.
• Datums en tijdstempels gebruiken ISO 8601 in UTC, zoals 2026-10-13T09:30:00.000Z.
• De duur van een opname en de tijden in een transcript zijn in seconden.
• Foutresponses hebben een vaste opbouw. Die vind je onder Fouten.
• Elke response op een geauthenticeerd request bevat X-RateLimit-Limit en X-RateLimit-Remaining. Lees meer over minuten, abonnementen en limieten.
• Met source=auto proberen we op YouTube, X, TikTok, Bluesky, Dailymotion en LinkedIn eerst bruikbare ondertitels in de oorspronkelijke taal. Zijn die er niet, dan gebruiken we speech-to-text. Niet elke video heeft ondertitels. Met captions (alleen ondertitels) halen we nooit audio op en schakelen we niet over op STT. Zonder bruikbaar spoor krijg je no_captions. Met source=stt of sprekerherkenning kies je meteen voor audio. In Bronnen en instellingen lees je welke beperkingen gelden en wanneer je tijdstempels per segment of per woord krijgt.

Wil je de API-specificatie in je eigen tooling gebruiken? Download OpenAPI als:

• JSON
• YAML

Geef je API-sleutel of token mee in de Authorization-header, als Authorization: Bearer <token>.

• API-sleutel: begint met t1_ en geeft toegang tot alle endpoints. Maak een sleutel aan op “API keys”.
• OAuth-toegangstoken: begint met t1o_. Clients zoals Claude en ChatGPT krijgen dit wanneer je ze via MCP koppelt. Het token gebruikt de scopes transcriptions:read en transcriptions:write.

Scope	Toegang tot
transcriptions:read	GET /v1/transcriptions, GET /v1/transcriptions/:id, GET /v1/transcriptions/:id/upload en GET /v1/account
transcriptions:write	POST /v1/transcriptions, DELETE /v1/transcriptions/:id en POST /v1/transcriptions/:id/upload/complete

• Mist het token de scope die je nodig hebt, dan krijg je 403 insufficient_scope.
• Ontbreekt de sleutel of het token, of is die ongeldig, dan krijg je 401 unauthorized.

Voor het versturen van chunks gebruik je een ander token. Geef bij PUT /v1/transcriptions/:id/upload/chunks/:index de header X-Upload-Token mee. Je krijgt dat token bij het aanmaken van de upload. De stappen staan bij Bestanden uploaden.

Geef bij POST /v1/transcriptions een Idempotency-Key-header mee. Dan kun je het request veilig herhalen.

Kies een waarde van 1 tot 255 tekens en stuur die als header, niet als queryparameter.

• Herhaal je het request met dezelfde sleutel en parameters, dan krijg je de oorspronkelijke transcriptie terug en betaal je niet opnieuw.
• Gebruik je dezelfde sleutel met andere parameters, dan krijg je 409 idempotency_conflict.
• Maak je een upload in chunks aan, dan levert hetzelfde request met dezelfde sleutel een nieuw uploadtoken op.

• Een fout bij een request betekent dat de API je aanroep meteen weigert.
• Een fout tijdens de transcriptie ontstaat pas nadat de API die heeft geaccepteerd. Dan staat status op failed.

Zo ziet een foutresponse eruit

Bij een geweigerd /v1-request krijg je een error-object met code, message en retryable.

• Laat je code reageren op code.
• Gebruik message voor de uitleg aan de gebruiker. De tekst kan veranderen.
• Staat retryable op true, dan kan hetzelfde request later wel slagen.

Afhankelijk van de fout krijg je naast retryable extra velden:

Veld	Foutcode	Wat staat erin?
action_url	insufficient_minutes	De link om een abonnement te nemen of minuten bij te kopen.
minutes_needed, minutes_remaining	insufficient_minutes	Het aantal benodigde minuten en je huidige saldo. Het benodigde aantal is null zolang de duur nog onbekend is.
supported_platforms	unsupported_platform	De toegestane platforms: ["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"].
missing_chunks	upload_incomplete	De indexen van de chunks die de server nog mist.
max_bytes	media_too_large	Jouw maximale bestandsgrootte in bytes.
params	invalid_request	Bij ongeldige body- of queryvelden een object dat per veld uitlegt wat je moet aanpassen.

Wanneer de API je request weigert

HTTP-status	code	Opnieuw proberen?	Oorzaak
400, 422	invalid_request	Nee	Een parameter of bodyveld ontbreekt of is ongeldig. Dit geldt ook voor ongeldige JSON en combinaties zoals diarize met source: "captions" of reuse_recent met webhook_url.
422	invalid_url	Nee	De link is niet geldig of komt niet overeen met platform. Gebruik YouTube, X, TikTok, Instagram, Facebook, Bluesky of een ander platform uit Bronnen en instellingen.
422	unsupported_platform	Nee	De opgegeven waarde voor platform is niet toegestaan.
422	unsupported_media	Nee	De bestandsextensie wordt niet ondersteund.
401	unauthorized	Nee	Je API-sleutel of token ontbreekt, is ongeldig, verlopen of ingetrokken. Ook een ongeldig of verlopen uploadtoken geeft deze fout.
403	insufficient_scope	Nee	Het OAuth-token heeft geen transcriptions:read of transcriptions:write waar die scope nodig is.
403	email_not_verified	Nee	Je moet eerst je e-mailadres bevestigen om transcripties te kunnen starten.
402	insufficient_minutes	Nee	Je beschikbare saldo is 0 of je hebt te weinig minuten voor deze transcriptie.
402	no_active_plan	Nee	Je wilt minuten bijkopen, maar hebt geen actief betaald abonnement. Alleen het billing-endpoint van het dashboard geeft deze fout, niet de transcriptie-endpoints.
404	not_found	Nee	De transcriptie bestaat niet of is van een ander team.
409	upload_incomplete	Nee	De server mist nog chunks. Verstuur die en rond de upload daarna opnieuw af.
409	invalid_state	Nee	De transcriptie wacht niet meer op een upload. Je kunt geen chunks meer sturen en de upload niet meer afronden.
409	idempotency_conflict	Nee	Je hebt deze Idempotency-Key eerder met andere parameters gebruikt.
413	media_too_large	Nee	Het bestand overschrijdt je uploadlimiet. Bekijk Bestanden uploaden.
413	invalid_request	Nee	De JSON-body is groter dan 1 MB. Bij te grote bestanden krijg je media_too_large.
429	rate_limited	Ja	Je stuurt te veel requests per minuut. Wacht het aantal seconden uit Retry-After.
429	too_many_active_jobs	Ja	Er lopen te veel transcripties of er staan te veel uploads open. Wacht het aantal seconden uit Retry-After.
500	internal_error	Ja	Er gaat iets mis bij transcript1. Probeer het na een korte pauze opnieuw.
503	service_unavailable	Ja	transcript1 is even niet beschikbaar. Probeer het na een korte pauze opnieuw.

Bij browserrequests met een inlogcookie controleren we ook vanaf welke site het request komt. Een andere site krijgt 403 forbidden_origin.

Voor API-requests met een Authorization-header geldt die controle niet.

In elke 429-response staat Retry-After: het aantal seconden dat je moet wachten. De limieten zelf vind je bij Minuten, abonnementen en limieten.

Wanneer stuur je een request opnieuw?

• Herhaal alleen requests met retryable op true: rate_limited, too_many_active_jobs, internal_error en service_unavailable.
• Houd de wachttijd uit Retry-After aan. Ontbreekt die header, wacht dan bij elke poging langer.
• Gebruik bij het herhalen van POST /v1/transcriptions dezelfde Idempotency-Key-header. Zo betaal je niet dubbel als het eerste request toch is gelukt.
• Pas bij alle andere codes eerst je request aan voordat je het nog eens verstuurt.

Als een transcriptie later mislukt

Loopt een transcriptie vast, dan staat status op failed. In het error-object staan code en message.

Ook na een geslaagd request kan de transcriptie nog mislukken. Controleer error dus tijdens het pollen of bij een webhook van het type transcription.failed.

error.code	Wat is er mis?	Wat kun je doen?
media_unavailable	De video bestaat niet of is niet meer beschikbaar.	Niet opnieuw proberen. Controleer de URL.
media_private	De video is afgeschermd.	Gebruik een openbare post of een openbare of verborgen YouTube-video. Hetzelfde request herhalen helpt niet.
login_required	Je moet op het platform ingelogd zijn om de video te bekijken.	Niet opnieuw proberen. Deze fout is definitief; we proberen het niet automatisch opnieuw.
no_audio	Er zit geen audiospoor in de video.	Niet opnieuw proberen. Deze fout is definitief; we proberen het niet automatisch opnieuw.
age_restricted	De video heeft een leeftijdsbeperking.	Hetzelfde request herhalen helpt niet. Upload het bestand.
live_stream	De uitzending loopt nog of is nog niet begonnen.	Probeer het na afloop van de uitzending.
no_captions	Je zette source op captions, maar er is geen bruikbaar ondertitelspoor.	Kies source: "auto" of "stt".
media_too_long	De opname duurt langer dan de 5 uur die speech-to-text aankan.	Splits het bestand. Hetzelfde request herhalen helpt niet.
unsupported_media	Het bestand is niet leesbaar of heeft geen audiospoor.	Stuur een ondersteund bestand; herhaal niet hetzelfde request.
no_speech	Geen spraak gedetecteerd.	Niet opnieuw proberen.
unsupported_language	We ondersteunen de taal van deze opname niet.	Kies voor language een ondersteunde code of "auto"; probeer niet opnieuw met dezelfde instelling.
insufficient_minutes	Je saldo was op voordat we de minuten konden afschrijven.	Koop eerst minuten bij en probeer het dan opnieuw.
fetch_failed	Ook na meerdere pogingen konden we de opname niet ophalen.	Probeer het later opnieuw.
transcription_failed	Ook na meerdere pogingen lukte speech-to-text niet.	Probeer het later opnieuw.

Mislukt een transcriptie of annuleer je die, dan betaal je niets. Hadden we al minuten afgeschreven, dan krijg je die terug.

Met webhook_url laat je je server weten wanneer de transcriptie klaar is. Geef die URL mee bij het aanmaken. Bij een geslaagde of mislukte transcriptie stuurt transcript1 daar een ondertekend POST-request naartoe.

Je kunt webhooks alleen via de REST API instellen. De MCP-server heeft hiervoor geen parameter.

Geef je webhook-URL mee

Bij POST /v1/transcriptions geef je webhook_url op deze manier mee:

• Bij een ondersteunde videolink of het aanmaken van een upload in chunks: in de JSON-body.
• Bij een bestand dat je in één request uploadt: als formulierveld.

Gebruik een URL die:

• HTTPS gebruikt.
• Geen gebruikersnaam of wachtwoord bevat.
• Uitkomt op een openbaar adres.

Verwijst de URL naar een privéadres, loopback-adres, link-local-adres of een ander niet-openbaar adres, dan krijg je 422 invalid_request. We controleren het adres bij het aanmaken en opnieuw bij elke poging om de webhook te versturen.

Je kunt webhook_url niet samen met reuse_recent=true gebruiken.

Welke events ontvang je?

type	Wanneer ontvang je dit?
transcription.completed	Zodra de status completed is.
transcription.failed	Zodra de status failed is. In data.error staan de code en message.

Annuleer je een transcriptie, dan sturen we geen webhook.

Wat staat er in het request?

De webhook heeft een JSON-body met deze velden:

• In created_at staat wanneer het event is aangemaakt.
• In data staat het transcriptieobject, zonder het veld transcript.

Haal de tekst op met GET /v1/transcriptions/:id. Gebruik daarvoor de id uit data.

Deze headers komen mee:

• Content-Type: application/json
• User-Agent: transcript1-webhooks/1.0
• X-Transcript1-Signature; hieronder lees je hoe je die controleert.

Controleer de handtekening

In elk webhookrequest staat X-Transcript1-Signature, met de waarde t=<unix seconds>,v1=<hex digest>.

• t geeft in Unix-seconden aan wanneer we het request hebben ondertekend.
• v1 bevat de HMAC-SHA256 als hexwaarde. Bereken die over "<t>.<raw body>": t, een punt en de body zoals je die hebt ontvangen. Gebruik je volledige geheime sleutel, dus inclusief whsec_.

Controleer de handtekening op de oorspronkelijke bytes, vóór je de JSON parset. Zet je geparste JSON weer om naar tekst, dan kunnen spaties of de veldvolgorde anders zijn. De handtekening klopt dan niet meer.

• Vergelijk de handtekeningen in constante tijd.
• Weiger requests waarvan t te ver van de huidige tijd ligt. De voorbeelden staan een verschil van 5 minuten toe.
• Laat Express de body als tekst inlezen, zonder die eerst te parsen.
• Geef bij Flask request.get_data(as_text=True) door als raw_body.

Je geheime sleutel beheren

Je team heeft één geheime sleutel die met whsec_ begint. We gebruiken die voor de webhooks van alle transcripties die je team aanmaakt.

Je kunt de sleutel bekijken of vervangen op “Webhooks”.

Een vervanging gaat direct in. Elke webhook die we daarna versturen, gebruikt de nieuwe sleutel.

Aflevering en nieuwe pogingen

• Antwoordt je server met 2xx, dan beschouwen we de webhook als afgeleverd.
• Een andere statuscode, een verbindingsfout of geen antwoord binnen 10 seconden telt als een mislukte poging.
• We proberen het maximaal 6 keer in totaal. Tussen de pogingen loopt de wachttijd exponentieel op: 2, 4, 8, 16 en 32 minuten. De laatste poging is ongeveer een uur na de eerste.
• Geef meteen de uiteindelijke URL op. transcript1 volgt geen redirects; ook 3xx telt als mislukt.
• Dezelfde webhook kan vaker aankomen, bijvoorbeeld als je server pas na de time-out antwoordt. Voorkom dubbele verwerking met data.id en type.