Quickstart

Three requests take a video link to a transcript file. You need an API key: create one on the API keys page. It is shown once. New accounts get 50 free credits every 30 days.

1. Submit a link#

mode: "auto" uses the video's captions when it has them (1 credit) and AI transcription when it does not (2 credits per minute, paid plans). The Idempotency-Key is any string of 8 to 128 characters you choose; sending the same key again returns the same job instead of creating a second one.

curl -X POST https://api.transcriptdock.com/v1/jobs \
  -H "Authorization: Bearer td_live_YOUR_KEY" \
  -H "Idempotency-Key: my-first-job" \
  -H "Content-Type: application/json" \
  -d '{ "source": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }, "mode": "auto" }'

{
  "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": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": null, "upload_id": null },
  "options": { "mode": "auto", "language": null, "caption_preference": "prefer_creator" },
  "created_at": "2026-09-16T10:00:00.000Z"
}

2. Wait for it#

?wait=25 holds the request for up to 25 seconds and returns as soon as the job finishes. Captions usually take a few seconds; AI transcription takes about a quarter of the video's length. If status is still not succeeded, failed or cancelled, call it again.

curl "https://api.transcriptdock.com/v1/jobs/11111111-1111-4111-8111-111111111111?wait=25" \
  -H "Authorization: Bearer td_live_YOUR_KEY"

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "succeeded",
  "stage": null,
  "result_id": "22222222-2222-4222-8222-222222222222",
  "error": null,
  "billing": { "credits_reserved": 0, "credits_charged": 1, "kind": "captions" },
  "source": { "platform": "youtube", "media_id": "dQw4w9WgXcQ", "canonical_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": null, "upload_id": null },
  "options": { "mode": "auto", "language": null, "caption_preference": "prefer_creator" },
  "created_at": "2026-09-16T10:00:00.000Z"
}

3. Get the transcript#

result_id is the transcript. Export it as txt, srt, vtt or json (full text, timed segments, word timings for AI transcription). Exports are free and unlimited.

curl "https://api.transcriptdock.com/v1/transcripts/22222222-2222-4222-8222-222222222222/export?format=srt" \
  -H "Authorization: Bearer td_live_YOUR_KEY"

1
00:00:00,000 --> 00:00:02,400
Never gonna give you up
 
2
00:00:02,400 --> 00:00:04,900
Never gonna let you down

What next#

• Submitting the same link again is free: the stored result is returned.
• Many videos at once: batches, up to 50 per request.
• Your own files: uploads.
• No polling: webhooks call you when a job finishes.
• From Claude, Cursor or another AI agent: MCP.