API-referens

Så fungerar det#

Varje transkript skapas via ett jobb. Du skickar in en källa, jobbet körs i bakgrunden, och när det lyckas pekar det på ett transkript som du kan läsa eller exportera så ofta du vill. Bas-URL: https://www.transcriptdock.com. Alla förfrågningar och svar är 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"

Autentisering#

Skapa nycklar på sidan API-nycklar. En nyckel visas en gång, ser ut som td_live_... och läggs i Authorization-headern i varje förfrågan. Nycklar har behörigheter som väljs när de skapas: jobs:read, jobs:write, transcripts:read, uploads:write. Skapa en nyckel per integration så att du kan återkalla den var för sig.

Authorization: Bearer td_live_YOUR_KEY

Idempotency-Key#

Krävs på POST /v1/jobs, /v1/batches, /v1/jobs/{id}/retry, /v1/video-discoveries och /v1/language-discoveries: en valfri sträng på 8 till 128 utskrivbara ASCII-tecken. Om du skickar samma nyckel med samma innehåll inom 48 timmar returneras det ursprungliga objektet, så att en upprepad förfrågan aldrig skapar eller debiterar två gånger. Samma nyckel med annat innehåll returnerar 409 IDEMPOTENCY_CONFLICT. En bra nyckel är ditt eget id för det du transkriberar.

X-Request-Id#

Varje svar har ett. Ange det när du kontaktar supporten.

Slutpunkter#

Skapa ett jobb#

source.urlstringValfri

En publik video: YouTube (watch?v=, youtu.be, shorts, live) eller TikTok (tiktok.com/@user/video/…, vm.tiktok.com-delningslänkar). Alla andra https-länkar till en ljud- eller videofil behandlas som direktmedialänkar (AI-transkribering). En av url eller upload_id krävs.

source.upload_iduuidValfri

En fil du har laddat upp (se Uppladdningar). Alltid AI-transkribering.

mode"captions_only" | "auto" | "transcribe"Obligatorisk

captions_only: videons egna undertexter, 1 kredit; misslyckas med NO_CAPTIONS om det inte finns några. auto: undertexter när de finns (1 kredit), annars AI-transkribering. transcribe: alltid AI-transkribering av ljudet, 2 krediter per påbörjad minut, med ordtider. AI-transkribering kräver ett betalt abonnemang.

caption_languagesstring[]Valfri

Önskade undertextspråk i prioritetsordning, t.ex. ["en", "es"], upp till 5. Standard: videons standardspår. Endast captions_only och auto.

caption_preference"prefer_creator" | "creator_only" | "automatic_only"Valfri

Om undertexter som skaparen laddat upp, YouTubes automatiska undertexter eller båda ska godtas (standard prefer_creator: skaparens först).

languagestringValfri

Talat språk som ledtråd för AI-transkribering (BCP 47). Standard: identifiera automatiskt.

max_creditsintegerValfri

Utgiftstak för AI-transkribering. Mediet mäts först; om det skulle kosta mer misslyckas jobbet med BUDGET_EXCEEDED och inget debiteras. Standard: tillräckligt för 2 timmar.

webhook_endpoint_iduuidValfri

Tar emot job.succeeded / job.failed på den här webhook-slutpunkten.

metadataobjectValfri

Upp till 10 strängvärden (nycklar ≤ 64, värden ≤ 256 tecken). Skickas tillbaka i webhook-händelser. Påverkar inte cachen.

Svarar 202 med jobbet. Om din arbetsyta redan har ett transkript för samma video och samma alternativ returneras 200 med ett lyckat jobb 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"
}

Jobbobjektet#

iduuidValfri

Jobbets id.

statusstringValfri

queued → processing (→ awaiting_provider under AI-transkribering) → succeeded, failed eller cancelled. De tre sista är slutliga.

stagestring | nullValfri

Var ett pågående jobb befinner sig: resolve, captions, acquire_audio, submit_asr, wait_asr, finalize. Endast informativt.

result_iduuid | nullValfri

Transkriptet, när jobbet har lyckats.

errorobject | nullValfri

Vid fel: code, message, retryable och valfritt details.detail. Samma koder som under Fel.

billingobjectValfri

credits_reserved (reserverade under körningen, 0 när jobbet är klart), credits_charged (slutlig), kind: captions, ai_transcription eller cached.

sourceobjectValfri

platform, media_id, canonical_url, title, upload_id.

optionsobjectValfri

mode, language, caption_preference i den form de accepterades.

created_atdate-timeValfri

UTC.

Hämta ett jobb#

Returnerar jobbet. Med wait (0 till 25 sekunder) hålls förfrågan öppen och returnerar så snart jobbet är slutligt, så ett anrop ersätter en pollingloop. Läsningar har en egen gräns på 120 per minut.

Lista jobb#

Nyast först, limit 1 till 100. Skicka tillbaka svarets next_cursor som cursor för nästa sida. Lägg till platform och source_id (jobbets source.media_id) tillsammans för att bara se jobben för en video, i valfritt läge. Så kontrollerar en klient om arbetsytan redan har ett transkript innan den skickar in igen.

Avbryt ett jobb#

Avbryter ett jobb som ännu inte har startat AI-transkribering; reservationen släpps. Senare än så returneras 409 CANCELLATION_NOT_ALLOWED och jobbet slutförs.

Försök ett jobb igen#

Skapar ett nytt jobb från ett misslyckat jobb vars fel var retryable. Kräver en ny Idempotency-Key; valfri body { "max_credits": 40 }. Prissätts som ett nytt jobb. Fel som är slutgiltiga (privat video, inga undertexter) returnerar 409 JOB_NOT_RETRYABLE: rätta indata och skicka in igen.

Transkriptet#

iduuidValfri

Samma som jobbets result_id.

sourceobjectValfri

platform, media_id, canonical_url, title.

source_originstringValfri

creator_captions, platform_captions (undertexter som plattformen genererat, till exempel YouTubes automatiska undertexter) eller speech_recognition (AI-transkribering).

languagestring | nullValfri

BCP 47-taggen för texten.

textstringValfri

Hela transkriptet som ren text.

segmentsarrayValfri

Delar av undertextstorlek: { start, end, text } i sekunder.

wordsarray | nullValfri

{ start, end, text, confidence } per ord. Endast AI-transkribering.

timing_granularity"word" | "segment" | "none"Valfri

Finaste tidsättningen som finns.

duration_secondsnumber | nullValfri

Mediets längd.

extraction_versionstringValfri

Versionen av pipelinen som tog fram resultatet.

recognitionobject | nullValfri

Endast AI-transkribering: model, profile, quality_status (validated_language: vi har testat det; provider_supported: modellen listar det; experimental_language: kvaliteten kan variera).

created_atdate-timeValfri

UTC.

{
  "id": "22222222-2222-4222-8222-222222222222",
  "source": { "platform": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Never Gonna Give You Up" },
  "source_origin": "creator_captions",
  "language": "en",
  "text": "Never gonna give you up. Never gonna let you down.",
  "segments": [
    { "start": 0, "end": 2.4, "text": "Never gonna give you up" },
    { "start": 2.4, "end": 4.9, "text": "Never gonna let you down" }
  ],
  "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"
}

Transkript sparas under ditt abonnemangs lagringstid (7 dagar på provperioden, 30 på Starter, 90 på Pro och Scale). DELETE /v1/transcripts/{id} tar bort ett transkript i förtid.

Exportera ett transkript#

Gratis och obegränsat. srt och vtt kräver tidsättning. Ett transkript utan den returnerar 422 TIMESTAMPS_UNAVAILABLE.

Batcher#

En förfrågan, många videor. Varje post har samma fält som Skapa ett jobb; hela batchen accepteras eller avvisas tillsammans. Poster per batch: 1 på provperioden, 10 på Starter, 25 på Pro, 50 på Scale.

itemsJobRequest[]Obligatorisk

1 till 50 jobbförfrågningar.

webhook_endpoint_iduuidValfri

Tar emot en batch.completed när varje post är slutlig.

metadataobjectValfri

Skickas tillbaka i händelsen batch.completed.

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

Batchobjektet har status (queued, processing, succeeded, partial_success, failed, cancelled), antal (total_items, succeeded_items, failed_items, cancelled_items) och items, där varje post har sitt job_id. Läs den med GET /v1/batches/{id}; varje post är ett vanligt jobb.

Uppladdningar#

Ditt eget ljud eller din egen video (mp3, wav, m4a, ogg, aac, mp4, webm; upp till 250 MB och 2 timmar). Reservera en plats, PUT:a filen till den signerade URL:en, markera den som klar och skicka sedan in den som ett jobb med source.upload_id. Uppladdningar använder alltid AI-transkribering.

# 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" }'

filenamestringObligatorisk

Upp till 255 tecken.

content_typestringObligatorisk

Filens MIME-typ, t.ex. audio/mpeg eller video/mp4. Skicka samma värde i PUT-anropet.

bytesintegerObligatorisk

Exakt filstorlek. PUT-anropet måste matcha.

Den signerade URL:en är giltig i 24 timmar; reservera en ny plats efter det.

Webhooks#

Registrera en https-URL och skicka dess id som webhook_endpoint_id när du skickar in. Vi skickar en händelse när jobbet eller batchen är klar. Svaret innehåller signeringshemligheten secret en gång. Att registrera och inaktivera slutpunkter kräver en inloggad session, så gör det på sidan Webhooks i dashboarden. En API-nyckel får 403 FORBIDDEN där men kan lista slutpunkter.

urlstringObligatorisk

https-URL, upp till 2048 tecken.

descriptionstringValfri

En etikett för din egen referens.

Händelser#

{
  "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: hämta eller exportera result_id.
• job.failed: error innehåller felkoden.
• batch.completed: varje post är slutlig; läs batchen för resultat per post.

Svara med en 2xx inom några sekunder. Leveranser som misslyckas försöks igen med ökande väntetid och kan skickas om från dashboarden. En händelse kan komma mer än en gång: filtrera dubbletter på event_id.

Verifiera signaturen#

Headerna X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp och X-TranscriptDock-Signature. Signaturen är HMAC-SHA256 (hex) av {event_id}.{timestamp}.{raw_body} med din hemlighet. Avvisa allt som är äldre än fem minuter.

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));
}

Hitta videor#

Sök på YouTube eller lista en kanal, spellista eller TikTok-profil, och mata sedan in URL:erna i jobb. En sökning körs i bakgrunden som ett jobb: läs den med GET /v1/video-discoveries/{id} tills status är succeeded. 1 kredit per sida; resultaten sparas i 24 timmar.

kindstringObligatorisk

youtube_search, youtube_channel_videos, youtube_channel_search, youtube_playlist_videos eller tiktok_user_videos.

querystringValfri

Söktext (youtube_search, youtube_channel_search).

channelstringValfri

@handle, kanal-id eller kanal-URL (kanaltyper).

playliststringValfri

Spellist-id eller URL (youtube_playlist_videos).

userstringValfri

@user eller profil-URL (tiktok_user_videos).

limitintegerValfri

Videor per sida, 1 till 50, standard 20. TikTok: högst 10.

cursorstringValfri

next_cursor från föregående sida. Endast YouTube.

include_detailsbooleanValfri

Endast TikTok: hämta också gillningar, kommentarer, hashtags och undertextspråk per video.

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 }'

POST-anropet svarar 202 med status: "queued". En färdig GET /v1/video-discoveries/{id} ser ut så här:

{
  "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"
}

Undertextspråk för en video#

Body { "source": { "url": "https://www.youtube.com/watch?v=..." } } med en Idempotency-Key (endast YouTube, 1 kredit). Läs GET /v1/language-discoveries/{id} för listan över undertextspår med deras koder, om de är skapade av skaparen eller automatiska, och standardspåret. Använd koderna i caption_languages.

Användning och funktioner#

{
  "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 räknar redan bort credits_reserved (reservationer för pågående jobb). prepaid_credits är köpta krediter, som aldrig går ut.

subscription är Stripe-abonnemanget bakom ett betalt abonnemang och null utan ett sådant: dess status, faktureringsintervallet (monthly eller yearly), cancel_at_period_end och current_period_end, alltså när abonnemanget förnyas eller upphör. period_end är när de månatliga krediterna förnyas, varje månad även på årsabonnemang.

Vad din nyckel kan göra just nu: per källa (youtube, tiktok, instagram, upload, direct) vilka lägen som är tillgängliga, samt gränser och priser. Läs detta i stället för att hårdkoda det. Provperioden rapporterar till exempel auto och transcribe som 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"
}

Hastighetsgränser#

Över en gräns får du 429 RATE_LIMITED med en retry-after-header (sekunder) och details.detail som namnger gränsen. Inget debiteras. Webhooks och ?wait=25 håller dig långt under läsgränsen.

Fel#

Alla fel har samma form. retryable: true betyder att samma förfrågan kan lyckas senare: vänta retry-after sekunder om den finns, annars några sekunders väntan, och använd samma Idempotency-Key så att inget dubbleras. Alla andra fel kräver en ändring på din sida.

{
  "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"
}

Ett jobb som misslyckas efter att det godtagits får fortfarande 200 på GET /v1/jobs/{id}, med status: "failed" och samma felobjekt i error. Ett misslyckat jobb debiteras inte.

Koder#