API-referentie

Hoe het werkt#

Elke transcriptie loopt via een taak. Je dient een bron in, de taak draait op de achtergrond, en wanneer die slaagt, verwijst hij naar een transcriptie die je zo vaak als je wilt kunt lezen of exporteren. Basis-URL: https://www.transcriptdock.com. Alle verzoeken en antwoorden zijn JSON.

# 1. Submit
curl -X POST https://www.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: video-7680721699171601694" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "url": "https://www.tiktok.com/@tiktok/video/7680721699171601694" }, "mode": "captions_only" }'
 
# 2. Wait (returns as soon as the job finishes, up to 25 s per call)
curl "https://www.transcriptdock.com/v1/jobs/11111111-1111-4111-8111-111111111111?wait=25" \
  -H "Authorization: Bearer td_live_YOUR_KEY"
 
# 3. Export
curl "https://www.transcriptdock.com/v1/transcripts/22222222-2222-4222-8222-222222222222/export?format=srt" \
  -H "Authorization: Bearer td_live_YOUR_KEY"

Authenticatie#

Maak sleutels aan op de pagina API keys. Een sleutel wordt één keer getoond, ziet eruit als td_live_... en gaat in de Authorization-header van elk verzoek. Sleutels krijgen bij het aanmaken scopes: jobs:read, jobs:write, transcripts:read, uploads:write. Maak per koppeling een eigen sleutel aan, zodat je er één apart kunt intrekken.

Authorization: Bearer td_live_YOUR_KEY

Idempotency-Key#

Verplicht bij POST /v1/jobs, /v1/batches, /v1/jobs/{id}/retry, /v1/video-discoveries en /v1/language-discoveries: elke tekst van 8 tot 128 afdrukbare ASCII-tekens. Als je binnen 48 uur dezelfde sleutel met dezelfde body stuurt, krijg je het oorspronkelijke object terug, zodat een opnieuw verzonden verzoek nooit dubbel iets aanmaakt of afrekent. Dezelfde sleutel met een andere body geeft 409 IDEMPOTENCY_CONFLICT. Een goede sleutel is je eigen id voor wat je transcribeert.

X-Request-Id#

Elk antwoord bevat er een. Vermeld hem wanneer je contact opneemt met support.

Endpoints#

Een taak aanmaken#

source.urlstringOptioneel

Een openbare video: YouTube (watch?v=, youtu.be, shorts, live) of TikTok (tiktok.com/@user/video/…, deelslinks van vm.tiktok.com). Elke andere https-link naar een audio- of videobestand wordt behandeld als directe medialink (AI-transcriptie). Een van url of upload_id is verplicht.

source.upload_iduuidOptioneel

Een bestand dat je hebt geüpload (zie Uploads). Altijd AI-transcriptie.

mode"captions_only" | "auto" | "transcribe"Verplicht

captions_only: de eigen ondertitels van de video, 1 credit; mislukt met NO_CAPTIONS als die er niet zijn. auto: ondertitels als die bestaan (1 credit), anders AI-transcriptie. transcribe: altijd AI-transcriptie van de audio, 2 credits per begonnen minuut, met woordtijden. AI-transcriptie vereist een betaald abonnement.

caption_languagesstring[]Optioneel

Gewenste ondertiteltalen in volgorde, bijvoorbeeld ["en", "es"], maximaal 5. Standaard: de standaardtrack van de video. Alleen voor captions_only en auto.

caption_preference"prefer_creator" | "creator_only" | "automatic_only"Optioneel

Of je ondertitels van de maker, de automatische ondertitels van YouTube of beide accepteert (standaard prefer_creator: eerst die van de maker).

languagestringOptioneel

Hint voor de gesproken taal bij AI-transcriptie (BCP 47). Standaard: automatisch herkennen.

max_creditsintegerOptioneel

Uitgavenlimiet voor AI-transcriptie. De media wordt eerst gemeten; kost het meer, dan mislukt de taak met BUDGET_EXCEEDED en wordt er niets afgeschreven. Standaard: genoeg voor 2 uur.

webhook_endpoint_iduuidOptioneel

Ontvang job.succeeded / job.failed op deze webhook.

metadataobjectOptioneel

Maximaal 10 tekstwaarden (sleutels ≤ 64, waarden ≤ 256 tekens). Komt terug in webhook-events. Heeft geen invloed op caching.

Geeft 202 terug met de taak. Heeft je werkruimte al een transcriptie voor dezelfde video en opties, dan geeft hij 200 terug met een geslaagde taak, gratis (billing.kind: "cached").

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "queued",
  "stage": "resolve",
  "result_id": null,
  "error": null,
  "billing": { "credits_reserved": 2, "credits_charged": 0, "kind": "captions" },
  "source": { "platform": "tiktok", "media_id": "7680721699171601694", "canonical_url": "https://www.tiktok.com/@tiktok/video/7680721699171601694", "title": null, "upload_id": null },
  "options": { "mode": "auto", "language": null, "caption_preference": "prefer_creator" },
  "created_at": "2026-09-16T10:00:00.000Z"
}

Het taakobject#

iduuidOptioneel

Taak-id.

statusstringOptioneel

queued → processing (→ awaiting_provider tijdens AI-transcriptie) → succeeded, failed of cancelled. De laatste drie zijn definitief.

stagestring | nullOptioneel

Waar een lopende taak staat: resolve, captions, acquire_audio, submit_asr, wait_asr, finalize. Alleen ter informatie.

result_iduuid | nullOptioneel

De transcriptie, zodra de taak is geslaagd.

errorobject | nullOptioneel

Bij een fout: code, message, retryable en optioneel details.detail. Dezelfde codes als bij Fouten.

billingobjectOptioneel

credits_reserved (gereserveerd tijdens het draaien, 0 als de taak klaar is), credits_charged (definitief), kind: captions, ai_transcription of cached.

sourceobjectOptioneel

platform, media_id, canonical_url, title, upload_id.

optionsobjectOptioneel

mode, language, caption_preference zoals geaccepteerd.

created_atdate-timeOptioneel

UTC.

Een taak ophalen#

Geeft de taak terug. Met wait (0 tot 25 seconden) blijft het verzoek open en geeft het antwoord zodra de taak definitief is. Eén aanroep vervangt zo een pollinglus. Lezen heeft een eigen limiet van 120 per minuut.

Taken tonen#

Nieuwste eerst, limit 1 tot 100. Geef de next_cursor van het antwoord terug als cursor voor de volgende pagina. Voeg platform en source_id samen toe (de source.media_id van een taak) om alleen de taken voor één video te zien, in elke modus. Zo controleert een client of de werkruimte al een transcriptie heeft voordat hij opnieuw indient.

Een taak annuleren#

Annuleert een taak waarvan de AI-transcriptie nog niet is gestart; de reservering wordt vrijgegeven. Daarna geeft hij 409 CANCELLATION_NOT_ALLOWED terug en maakt de taak af.

Een taak opnieuw proberen#

Maakt een nieuwe taak aan vanuit een mislukte taak waarvan de fout retryable was. Heeft een nieuwe Idempotency-Key nodig; optionele body { "max_credits": 40 }. Wordt geprijsd zoals een nieuwe taak. Definitieve fouten (privévideo, geen ondertitels) geven 409 JOB_NOT_RETRYABLE terug: pas de invoer aan en dien opnieuw in.

De transcriptie#

iduuidOptioneel

Hetzelfde als de result_id van de taak.

sourceobjectOptioneel

platform, media_id, canonical_url, title.

source_originstringOptioneel

creator_captions, platform_captions (ondertitels die het platform heeft gegenereerd, zoals de automatische ondertitels van YouTube) of speech_recognition (AI-transcriptie).

languagestring | nullOptioneel

BCP 47-tag van de tekst.

textstringOptioneel

De hele transcriptie als platte tekst.

segmentsarrayOptioneel

Stukken van ondertitellengte: { start, end, text } in seconden.

wordsarray | nullOptioneel

{ start, end, text, confidence } per woord. Alleen bij AI-transcriptie.

timing_granularity"word" | "segment" | "none"Optioneel

Fijnste beschikbare timing.

duration_secondsnumber | nullOptioneel

Lengte van de media.

extraction_versionstringOptioneel

Versie van de pipeline die het resultaat heeft gemaakt.

recognitionobject | nullOptioneel

Alleen bij AI-transcriptie: model, profile, quality_status (validated_language: we hebben het getest; provider_supported: het model noemt de taal; experimental_language: de kwaliteit kan verschillen).

created_atdate-timeOptioneel

UTC.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "source": { "platform": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Voorbeeldvideo" },
  "source_origin": "creator_captions",
  "language": "nl",
  "text": "Welkom bij deze video. Vandaag bekijken we hoe het werkt.",
  "segments": [
    { "start": 0, "end": 2.4, "text": "Welkom bij deze video" },
    { "start": 2.4, "end": 4.9, "text": "Vandaag bekijken we hoe het werkt" }
  ],
  "words": null,
  "timing_granularity": "segment",
  "duration_seconds": 212.0,
  "recognition": null,
  "extraction_version": "worker-0.1.0",
  "created_at": "2026-09-16T10:00:14.000Z"
}

Transcripties worden bewaard voor de bewaartermijn van je abonnement (7 dagen bij de proef, 30 bij Starter, 90 bij Pro en Scale). DELETE /v1/transcripts/{id} verwijdert er eerder één.

Een transcriptie exporteren#

Gratis, onbeperkt. srt en vtt hebben timings nodig; een transcriptie zonder timings geeft 422 TIMESTAMPS_UNAVAILABLE terug.

Batches#

Eén verzoek, veel video's. Elk item heeft dezelfde velden als Een taak aanmaken; de hele batch wordt samen geaccepteerd of afgewezen. Items per batch: 1 bij de proef, 10 bij Starter, 25 bij Pro, 50 bij Scale.

itemsJobRequest[]Verplicht

1 tot 50 taakverzoeken.

webhook_endpoint_iduuidOptioneel

Ontvangt één batch.completed zodra elk item definitief is.

metadataobjectOptioneel

Komt terug in het batch.completed-event.

curl -X POST https://www.transcriptdock.com/v1/batches \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: playlist-2026-09-16" \
  -H "Content-Type: application/json" \
  -d '{ "items": [
        { "source": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "mode": "captions_only" },
        { "source": { "url": "https://www.tiktok.com/@tiktok/video/7680721699171601694" }, "mode": "captions_only" }
      ] }'

Het batchobject heeft status (queued, processing, succeeded, partial_success, failed, cancelled), aantallen (total_items, succeeded_items, failed_items, cancelled_items) en items, elk met zijn job_id. Lees het uit met GET /v1/batches/{id}; elk item is een gewone taak.

Uploads#

Je eigen audio of video (mp3, wav, m4a, ogg, aac, mp4, webm; tot 250 MB en 2 uur). Reserveer een plek, stuur het bestand met PUT naar de ondertekende URL, markeer het als voltooid en dien het daarna in als taak met source.upload_id. Uploads gebruiken altijd AI-transcriptie.

# 1. Reserve
curl -X POST https://www.transcriptdock.com/v1/uploads \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "interview.mp3", "content_type": "audio/mpeg", "bytes": 48213920 }'
# -> { "id": "33333333-...", "signed_upload_url": "https://...", "expires_at": "...", "status": "pending" }
 
# 2. Upload the bytes (same Content-Type you declared)
curl -X PUT "SIGNED_UPLOAD_URL" -H "Content-Type: audio/mpeg" --data-binary @interview.mp3
 
# 3. Complete
curl -X POST https://www.transcriptdock.com/v1/uploads/33333333-3333-4333-8333-333333333333/complete \
  -H "Authorization: Bearer td_live_YOUR_KEY"
 
# 4. Transcribe it
curl -X POST https://www.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: interview-01" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "upload_id": "33333333-3333-4333-8333-333333333333" }, "mode": "transcribe" }'

filenamestringVerplicht

Maximaal 255 tekens.

content_typestringVerplicht

Het MIME-type van het bestand, bijvoorbeeld audio/mpeg of video/mp4. Stuur dezelfde waarde mee bij de PUT.

bytesintegerVerplicht

Exacte bestandsgrootte. De PUT moet hiermee overeenkomen.

De ondertekende URL is 24 uur geldig; reserveer daarna een nieuwe plek.

Webhooks#

Registreer een https-URL en geef het id mee als webhook_endpoint_id wanneer je indient. Wij sturen een POST met een event zodra de taak of batch klaar is. Het antwoord bevat het ondertekeningsgeheim (secret) één keer. Endpoints registreren en uitschakelen vereist een ingelogde sessie, dus doe dat op de pagina Webhooks van het dashboard; een API-sleutel krijgt daar 403 FORBIDDEN, maar kan endpoints wel tonen.

urlstringVerplicht

https-URL, maximaal 2048 tekens.

descriptionstringOptioneel

Een label ter herkenning voor jezelf.

Events#

{
  "event_id": "44444444-4444-4444-8444-444444444444",
  "type": "job.succeeded",
  "created_at": "2026-09-16T10:00:14.000Z",
  "job_id": "11111111-1111-4111-8111-111111111111",
  "batch_id": null,
  "result_id": "22222222-2222-4222-8222-222222222222",
  "metadata": { "order": "8812" },
  "error": null
}

• job.succeeded: haal result_id op of exporteer hem.
• job.failed: error bevat de code.
• batch.completed: elk item is definitief; lees de batch voor de resultaten per item.

Antwoord binnen enkele seconden met een 2xx. Mislukte leveringen worden met oplopende wachttijd opnieuw geprobeerd en kunnen vanuit het dashboard opnieuw worden verstuurd. Een event kan meer dan één keer binnenkomen: filter dubbelen op event_id.

De handtekening controleren#

Headers X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp en X-TranscriptDock-Signature. De handtekening is de HMAC-SHA256 (hex) van {event_id}.{timestamp}.{raw_body} met je geheim. Wijs alles af dat ouder is dan vijf minuten.

import crypto from "node:crypto";
 
export function verify(eventId: string, timestamp: string, rawBody: string, signature: string, secret: string): boolean {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${eventId}.${timestamp}.${rawBody}`).digest("hex");
  return expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Video's zoeken#

Zoek op YouTube of toon een kanaal, afspeellijst of TikTok-profiel, en geef de URL's daarna door aan taken. Een videozoekopdracht draait op de achtergrond, net als een taak: lees hem uit met GET /v1/video-discoveries/{id} totdat status succeeded is. 1 credit per pagina; resultaten worden 24 uur bewaard.

kindstringVerplicht

youtube_search, youtube_channel_videos, youtube_channel_search, youtube_playlist_videos of tiktok_user_videos.

querystringOptioneel

Zoektekst (youtube_search, youtube_channel_search).

channelstringOptioneel

@handle, kanaal-id of kanaal-URL (kanaalsoorten).

playliststringOptioneel

Afspeellijst-id of -URL (youtube_playlist_videos).

userstringOptioneel

@user of profiel-URL (tiktok_user_videos).

limitintegerOptioneel

Video's per pagina, 1 tot 50, standaard 20. TikTok: maximaal 10.

cursorstringOptioneel

next_cursor van de vorige pagina. Alleen YouTube.

include_detailsbooleanOptioneel

Alleen TikTok: haalt ook per video de likes, reacties, hashtags en ondertiteltalen op.

curl -X POST https://www.transcriptdock.com/v1/video-discoveries \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: search-async-rust-1" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "youtube_search", "query": "async rust", "limit": 5 }'

De POST antwoordt met 202 en status: "queued". Een afgeronde GET /v1/video-discoveries/{id} ziet er zo uit:

{
  "id": "55555555-5555-4555-8555-555555555555",
  "kind": "youtube_search",
  "status": "succeeded",
  "request": { "kind": "youtube_search", "query": "async rust", "limit": 5 },
  "videos": [
    {
      "platform": "youtube",
      "video_id": "wXtngLBkK4Q",
      "url": "https://www.youtube.com/watch?v=wXtngLBkK4Q",
      "title": "Async Rust explained in 20 minutes",
      "channel_id": "UCSp-OaMpsO8K0KkOqyBl7_w",
      "channel_title": "Let's Get Rusty",
      "duration_s": 1155,
      "published_at": null,
      "published_text": "5 months ago",
      "view_count": 83635,
      "view_count_text": "83,635 views",
      "thumbnail_url": "https://i.ytimg.com/vi/wXtngLBkK4Q/hq720.jpg",
      "tiktok": null
    }
  ],
  "profile": null,
  "next_cursor": "opaque-token",
  "error": null,
  "created_at": "2026-09-16T12:00:00.000Z",
  "updated_at": "2026-09-16T12:00:03.000Z",
  "expires_at": "2026-09-17T12:00:00.000Z"
}

Ondertiteltalen van een video#

Body { "source": { "url": "https://www.youtube.com/watch?v=..." } } met een Idempotency-Key (alleen YouTube, 1 credit). Lees GET /v1/language-discoveries/{id} voor de lijst met ondertiteltracks met hun codes, of ze van de maker of automatisch zijn, en welke de standaard is. Gebruik de codes in caption_languages.

Gebruik en mogelijkheden#

{
  "plan": "pro",
  "period_end": "2026-10-16T00:00:00.000Z",
  "credits_remaining": 5840,
  "credits_total": 6000,
  "credits_reserved": 4,
  "prepaid_credits": 0,
  "transcribe_credits_per_minute": 2,
  "minimum_billable_seconds": 60,
  "subscription": {
    "status": "active",
    "interval": "yearly",
    "cancel_at_period_end": false,
    "current_period_end": "2027-09-16T00:00:00.000Z"
  }
}

credits_remaining houdt al geen rekening meer met credits_reserved (reserveringen voor lopende taken). prepaid_credits zijn gekochte credits; die verlopen nooit.

subscription is het Stripe-abonnement achter een betaald abonnement, en null zonder abonnement: de status, de facturatieperiode interval (monthly of yearly), cancel_at_period_end en current_period_end, wanneer het abonnement wordt verlengd of eindigt. period_end is het moment waarop de maandelijkse credits worden vernieuwd, elke maand, ook bij jaarabonnementen.

Wat je sleutel nu kan: per bron (youtube, tiktok, instagram, upload, direct) welke modi beschikbaar zijn, plus limieten en prijzen. Lees dit uit in plaats van het vast in je code te zetten; de proef meldt bijvoorbeeld auto en transcribe als false.

{
  "youtube": { "enabled": true, "captions_only": true, "auto": true, "transcribe": true, "social_acquisition_fee": true },
  "tiktok": { "enabled": true, "captions_only": true, "auto": true, "transcribe": true, "social_acquisition_fee": true },
  "instagram": { "enabled": false, "captions_only": false, "auto": false, "transcribe": false, "social_acquisition_fee": true, "native_captions": "unverified_disabled" },
  "upload": { "enabled": true, "captions_only": false, "auto": true, "transcribe": true, "social_acquisition_fee": false },
  "direct": { "enabled": true, "captions_only": false, "auto": true, "transcribe": true, "social_acquisition_fee": false },
  "max_duration_ms": 7200000,
  "max_media_bytes": 262144000,
  "export_formats": ["txt", "json", "srt", "vtt"],
  "recognition_profiles": ["standard"],
  "transcribe_credits_per_minute": 2,
  "minimum_billable_seconds": 60,
  "price_version": "2026-09-14",
  "asr_enabled": true,
  "instagram_enabled": false,
  "free_caption_credits": 50,
  "free_caption_credits_period": "month"
}

Limieten voor verzoeken#

Bij een overschreden limiet krijg je 429 RATE_LIMITED met een retry-after-header (in seconden) en details.detail met de naam van de limiet. Er wordt niets afgeschreven. Webhooks en ?wait=25 houden je ver onder de leeslimiet.

Fouten#

Elke fout heeft dezelfde vorm. retryable: true betekent dat hetzelfde verzoek later kan slagen: wacht retry-after seconden als die er is, anders een paar seconden, en gebruik dezelfde Idempotency-Key opnieuw zodat er niets dubbel komt. Bij elke andere fout moet je iets aan je kant aanpassen.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Not enough credits. Buy credits or upgrade your plan to continue.",
    "retryable": false,
    "details": { "detail": "This job needs more credits than you have left. Buy credits or upgrade your plan." },
    "doc_url": "https://www.transcriptdock.com/docs/api-reference#error-codes"
  },
  "request_id": "66666666-6666-4666-8666-666666666666"
}

Een taak die na acceptatie mislukt, krijgt nog steeds 200 bij GET /v1/jobs/{id}, met status: "failed" en hetzelfde foutobject in error. Voor een mislukte taak wordt niets afgeschreven.

Codes#