# TranscriptDock

> Transcripts from YouTube, TikTok and your own audio or video, through one REST API or straight from an AI agent over MCP.

One kind of credit. A caption transcript (the video's own subtitles) costs 1 credit. AI transcription of the audio (mode auto when there are no captions, mode transcribe, uploads, direct links) costs 2 credits per started minute and needs a paid plan. Every account starts with 50 free credits. Reading and exporting transcripts is free.

## Docs

- [Quickstart](https://transcriptdock.com/docs/quickstart): submit a link, wait for the job, export the transcript. Three requests.
- [API reference](https://transcriptdock.com/docs/api-reference): endpoints, fields, responses, batches, uploads, webhooks, video discovery, credits, rate limits, errors.
- [MCP](https://transcriptdock.com/docs/mcp): remote server at https://transcriptdock.com/mcp (Authorization: Bearer <api key>), tools, and setup for Claude Code, Claude Desktop, Cursor, Windsurf, OpenClaw.
- [Pricing and credits](https://transcriptdock.com/docs/pricing): plans, extra credits, when credits are charged.
- [Sources](https://transcriptdock.com/docs/platforms): accepted YouTube and TikTok URLs, file uploads, direct links, limits.
- [OpenAPI](https://transcriptdock.com/docs/openapi.yaml)

## Machine discovery

- [MCP server card](https://transcriptdock.com/mcp/server-card) and [AI catalog](https://transcriptdock.com/.well-known/ai-catalog.json)
- [llms-full.txt](https://transcriptdock.com/llms-full.txt): the API reference and MCP pages as one plain text file.

---

# API reference

Base URL: https://api.transcriptdock.com. JSON in and out.
Authentication: Authorization: Bearer td_live_<your key>. Keys are created on the dashboard and shown once.
POST /v1/jobs, /v1/batches, /v1/jobs/{id}/retry, /v1/video-discoveries and /v1/language-discoveries require an Idempotency-Key header (8 to 128 printable ASCII characters). The same key with the same body within 48 hours returns the original object; with a different body it returns 409 IDEMPOTENCY_CONFLICT.
Every response carries X-Request-Id.

## Flow

1. POST /v1/jobs with { "source": { "url": "<video url>" }, "mode": "auto" } -> 202 job { id, status: "queued" }.
2. GET /v1/jobs/{id}?wait=25 -> holds up to 25 s and returns the job as soon as status is succeeded, failed or cancelled. Repeat while it is not.
3. GET /v1/transcripts/{result_id}/export?format=txt|srt|vtt|json -> the transcript file. Free, unlimited.
Submitting the same video and options again returns the stored result for free (billing.kind "cached"). A video another customer already transcribed is served from cache instantly at the normal price.

## Endpoints

| Method | Path | Credits |
|---|---|---|
| POST | /v1/jobs | 1 per caption transcript, 2 per started minute of AI transcription |
| GET | /v1/jobs/{id}?wait=0..25 | free |
| GET | /v1/jobs?limit=&cursor= | free |
| POST | /v1/jobs/{id}/cancel | free |
| POST | /v1/jobs/{id}/retry | as a new job |
| POST | /v1/batches | per item, as above |
| GET | /v1/batches/{id} | free |
| GET | /v1/transcripts/{id} | free |
| GET | /v1/transcripts/{id}/export?format= | free |
| DELETE | /v1/transcripts/{id} | free |
| POST | /v1/uploads | free |
| POST | /v1/uploads/{id}/complete | free |
| POST | /v1/video-discoveries | 1 per page |
| GET | /v1/video-discoveries/{id} | free |
| POST | /v1/language-discoveries | 1 |
| GET | /v1/language-discoveries/{id} | free |
| POST/GET/DELETE | /v1/webhook-endpoints | free |
| GET | /v1/usage | free |
| GET | /v1/capabilities | free |

## Create a job

POST /v1/jobs
Fields: source.url (YouTube watch/youtu.be/shorts/live URL, TikTok video or vm.tiktok.com share link, or any https link to a media file) or source.upload_id; mode (required): captions_only (the video's captions, 1 credit, NO_CAPTIONS if none), auto (captions if present else AI transcription), transcribe (always AI transcription, 2 credits per started minute, word timings); caption_languages (string[], up to 5 BCP 47 tags in preference order); caption_preference (prefer_creator default, creator_only, automatic_only); language (BCP 47 hint for AI transcription); max_credits (cap for AI transcription; a job that would cost more fails with BUDGET_EXCEEDED before any charge); webhook_endpoint_id; metadata (up to 10 string values, echoed in webhook events).
AI transcription needs a paid plan: on the trial auto and transcribe return 402 PLAN_REQUIRED.

Job object: id, status (queued, processing, awaiting_provider, succeeded, failed, cancelled), stage, result_id, error { code, message, retryable, details? }, billing { credits_reserved, credits_charged, kind: captions | ai_transcription | cached }, source { platform, media_id, canonical_url, title, upload_id }, options { mode, language, caption_preference }, created_at.

## Transcript

GET /v1/transcripts/{id}: id, source, source_origin (creator_captions, platform_captions, speech_recognition), language, text, segments [{ start, end, text }] in seconds, words [{ start, end, text, confidence }] or null, timing_granularity (word, segment, none), duration_seconds, recognition { model, profile, quality_status: validated_language | provider_supported | experimental_language } or null, created_at.
Kept for the plan's retention (trial 7 days, Starter 30, Pro and Scale 90). DELETE removes one earlier.

## Batches

POST /v1/batches { items: [JobRequest, ...], webhook_endpoint_id?, metadata? }. Items per batch: trial 1, Starter 10, Pro 25, Scale 50. Accepted or rejected as a whole. GET /v1/batches/{id}: status (queued, processing, succeeded, partial_success, failed, cancelled), total_items, succeeded_items, failed_items, cancelled_items, items [{ job_id, item_index, status }].

## Uploads

POST /v1/uploads { filename, content_type, bytes } -> { id, signed_upload_url, expires_at (24 h) }. PUT the file to signed_upload_url with the same Content-Type. POST /v1/uploads/{id}/complete. Then POST /v1/jobs with { "source": { "upload_id": id }, "mode": "transcribe" }. Audio or video up to 250 MB and 2 hours.

## Webhooks

POST /v1/webhook-endpoints { url (https), description? } -> endpoint with a one-time secret. Pass its id as webhook_endpoint_id on jobs and batches. Events: job.succeeded, job.failed, batch.completed; body { event_id, type, created_at, job_id, batch_id, result_id, metadata, error }. Headers X-TranscriptDock-Event-Id, X-TranscriptDock-Timestamp, X-TranscriptDock-Signature = HMAC-SHA256 hex of "{event_id}.{timestamp}.{raw_body}" with the secret. Respond 2xx; failed deliveries retry with backoff; dedupe on event_id.

## Find videos

POST /v1/video-discoveries { kind, query?, channel?, playlist?, user?, limit?, cursor?, include_details? } with Idempotency-Key, 1 credit per page. Kinds: youtube_search (query), youtube_channel_videos, youtube_channel_search (channel as @handle, id or URL; search adds query), youtube_playlist_videos (playlist id or URL), tiktok_user_videos (user as @user or URL; at most 10, no paging; include_details adds likes, comments, hashtags, caption languages). GET /v1/video-discoveries/{id}: status, videos [{ platform, video_id, url, title, channel_title, duration_s, published_at, view_count, thumbnail_url, tiktok }], profile, next_cursor, error. Results kept 24 h.
POST /v1/language-discoveries { source: { url } } (YouTube, 1 credit) lists a video's caption tracks; use the codes in caption_languages.

## Usage and capabilities

GET /v1/usage: plan, period_end, credits_remaining (excludes holds), credits_total, credits_reserved, prepaid_credits, transcribe_credits_per_minute (2), minimum_billable_seconds (60).
GET /v1/capabilities (with your key): per source (youtube, tiktok, upload, direct) whether captions_only, auto and transcribe are available for your plan, plus max_duration_ms 7200000, max_media_bytes 262144000, export_formats.

## Credits

Charged only when a job succeeds; held while it runs; released on failure or cancel. auto holds 2 and charges 1 when captions were found. Plans: Trial 50 credits every 30 days (captions only, free), Starter $19 for 2,000 a month, Pro $49 for 6,000, Scale $149 for 20,000. Extra credits from $8/$7/$6 per 1,000 (Starter/Pro/Scale), 10% off from 10,000, 20% off from 50,000, never expire. Out of credits: 402 INSUFFICIENT_BALANCE.

## Rate limits

Submits per minute: trial 10, Starter 60, Pro 120, Scale 300. Jobs in progress: 10 / 100 / 500 / 2,000. Reads: 120 per minute. Over a limit: 429 RATE_LIMITED with retry-after (seconds), ratelimit-limit, ratelimit-remaining, ratelimit-reset headers and details.detail naming the limit.

## Errors

{ "error": { "code", "message", "retryable", "retry_after_seconds"?, "details": { "detail" }?, "doc_url" }, "request_id" }. retryable true (429, 503, 500): wait and resend with the same Idempotency-Key. Full code table: https://transcriptdock.com/docs/api-reference#error-codes. A job that fails after acceptance is 200 on GET /v1/jobs/{id} with status failed and the same error object; nothing is charged.

---

# MCP

Remote server (nothing to install): https://transcriptdock.com/mcp, Streamable HTTP, header Authorization: Bearer td_live_<key>.
Claude Code: claude mcp add --transport http transcriptdock https://transcriptdock.com/mcp --header "Authorization: Bearer td_live_<key>"
mcp.json: { "mcpServers": { "transcriptdock": { "type": "http", "url": "https://transcriptdock.com/mcp", "headers": { "Authorization": "Bearer td_live_<key>" } } } }
Local server (Claude Desktop, OpenClaw, stdio clients): { "mcpServers": { "transcriptdock": { "command": "npx", "args": ["-y", "@transcriptdock/mcp"], "env": { "TRANSCRIPTDOCK_API_KEY": "td_live_<key>", "TRANSCRIPTDOCK_BASE_URL": "https://transcriptdock.com" } } } }
Remote tool calls are capped at about 40 s; a still-running job comes back with its id for wait_for_job.

## Tools

- get_video_transcript { url, mode? (captions_only default, auto, transcribe), format? (text default, srt, vtt, segments), timeout_seconds? } -> transcript. Submits, waits, returns. 1 credit, or 2 per minute with AI transcription; repeats are free.
- transcribe { url, mode?, language?, max_credits?, idempotency_key } -> job.
- wait_for_job { job_id, timeout_seconds? } -> job.
- get_job { job_id } -> job. Free.
- get_transcript { transcript_id, format? (segments default, text, srt, vtt) }. Free.
- list_jobs { limit?, cursor? }. Free.
- search_youtube { query, limit?, cursor?, timeout_seconds? }. 1 credit per page.
- list_channel_videos { channel, limit?, cursor? }, get_channel_latest_videos { channel, limit? }, search_channel_videos { channel, query, limit?, cursor? }. 1 credit per page.
- list_playlist_videos { playlist, limit?, cursor? }. 1 credit per page.
- list_tiktok_user_videos { user, limit? (max 10), include_details? }. 1 credit.
- get_video_discovery { id }. Free.