API Reference

One curl call from a YouTube URL to a queued transcription:

curl -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer tsk_live_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "youtube",
    "url": "https://youtu.be/dQw4w9WgXcQ"
  }'

You'll get an integer id back. Block on GET /api/v1/transcriptions/<id>/wait?include=all (up to 45 s per call) until status is completed, or fetch /resultlater. Or register a webhook (see below) and we'll POST you when it's done. Prefer tools over HTTP? The same flow is exposed over MCP at https://transcribe.so/mcp (see below).

• Base URL: https://transcribe.so. Versioned prefix: /api/v1.
• Auth: every request carries Authorization: Bearer tsk_live_….
• Content type: JSON in/out, UTF-8.
• Identifiers: 4821 (plain integer) for transcriptions, tsk_live_… for API keys.
• Every response includes X-Request-Id. Quote it in support tickets.
• Rate limit: 60 requests / minute per key. Exceeded → 429 rate_limited.
• CORS: every /api/v1/* endpoint is open to any origin. Bearer auth, no cookies.
• Pricing: identical to /pricing. On subscription plans, transcription via the API is included ($0); Pay as you go bills the wallet at $1/hour.

The API authenticates with Bearer tokens on the Authorization header — API keys for scripts and integrations, no cookies. OAuth access tokens issued by the MCP connector flow are accepted on the same header and rate-limited per user rather than per key; the only difference is that webhook endpoints require an API key (OAuth tokens get 403 forbidden). Treat a key like a password.

Keys carry permissions and an optional monthly spend cap, both chosen when you create the key. Full access (default) can do everything; Read only keys are limited to GET endpoints and get 403 scope_forbidden on any POST/DELETE (they cannot create anything, including quotes and uploads; on /mcp they only see the read tools). A capped key stops starting transcription jobs with 402 spend_cap_exceededonce the month's spend would pass the cap (realtime sessions are not counted). OAuth tokens are always full access. GET /me echoes both under api_key.

Get a key

1. Sign in and visit /settings/api-keys.
2. Click Create key, give it a name (e.g. n8n-prod).
3. Copy the plaintext immediately — we show it once and never again. The server only stores sha256(key).

Smoke test

curl -sS https://transcribe.so/api/v1/me \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

Returns the authenticated user, current wallet balance, and plan tier.

Limits

• 20 active keys per user
• 60 requests / minute per key, on every plan
• On Pay as you go, the wallet is the spend cap; subscription plans meter processing minutes instead (below)

Per-plan processing limits

Enforced when you create a transcription — they never affect read endpoints:

• A file over your plan's length cap → 400 invalid_requestwith a message naming the cap. 12 h per file is the current pipeline maximum; your plan's cap from the table above applies first. Direct uploads are also bound by the 1 GB file-size cap; for longer high-bitrate files use a URL or YouTube source.
• Concurrent-job caps apply to subscription plans. On Pay as you go, the wallet is the effective limiter.
• Fair-use minutes are a hard wall on Pay as you go: exceeding the window → 429 rate_limited, same code as request throttling; the error.message says which wall you hit. Wait for the window to roll or upgrade.
• On subscription plans the fair-use figures are guidelines, not walls: jobs past them may queue at lower priority during peak hours, but are never rejected.

POST /api/v1/transcriptionsaccepts the same four sources as the dashboard's /transcriptions page. All four go through the same quote → wallet hold → enqueue path.

addons (string array, max 8) is accepted on POST /quotes and POST /transcriptions but rarely needed: speaker diarization is built into the standard pipeline, so omit it unless GET /api/v1/pipelines lists an add-on as compatible. Unknown codes return 400 addon_not_supported.

Every error response uses the same envelope:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Wallet balance too low. Top up your wallet at https://transcribe.so/billing.",
    "request_id": "req_a1b2c3d4e5f6",
    "doc_url": "https://transcribe.so/billing"
  }
}

• message inlines an actionable URL where one applies. Terminal users see the link without parsing JSON.
• doc_url always points at a stable docs section or dashboard surface for that error.
• request_id is also returned as X-Request-Id on every response — quote it in support tickets.

Retry guidance

• 429: honour the retry-after header (seconds); if absent, back off 60s.
• 500: exponential backoff (1, 2, 4, 8s, max 60s), cap at 5 attempts. Use the same Idempotency-Key so duplicates don't bill twice.
• 402: do not retry until the user tops up.
• 409 not_ready: call POST /timestamps/regenerate, then retry.
• 400 / 401 / 403 / 404: don't retry; fix the request.

POST endpoints accept an Idempotency-Keyheader. Use it on any request that creates or starts something, so retries don't double-bill or double-queue.

POST /api/v1/transcriptions
Idempotency-Key: 2026-04-30-podcast-ep-149

• First request runs normally. Subsequent requests with the same (api_key, idempotency_key) within 24h return the original response unchanged.
• Reusing the same key with a different body returns 400 invalid_request.
• 2xx and 4xx responses are cached; 5xx are not (so you can retry past transient bugs).
• Max key length: 128 chars. Use a UUID, content hash, or stable composite — anything that doesn't change across retries of the same logical request.

Transcriptions are async (~60s for 1-min audio, ~5min for an hour-long podcast). For long-running ops, ranked best-to-worst:

1. Webhook — best for fire-and-forget pipelines. Register one URL per API key, or pass callback_url on a single POST /transcriptions; we deliver an HMAC-signed transcription.completed POST when the job hits a terminal state. No connections held open, no rate-limit pressure, scales to any volume. Setup →
2. Long-poll /wait — best for synchronous "create-and-wait" flows where you can hold one HTTP connection. Server holds the response open up to timeout seconds (max 45) and returns as soon as the job finishes. One request per job.
   bashCopy

   curl -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
     "https://transcribe.so/api/v1/transcriptions/4821/wait?timeout=30&include=chapters,sections,qna"

3. Email notification — falls out automatically. Every user gets an email when their job completes. No code required.
4. Loop-polling GET /transcriptions/:id — don't. Naive polling every few seconds wastes tokens, eats rate limit, and gives you no faster signal than the long-poll. If your runtime can't hold a connection, use the webhook.

The synchronous endpoints (POST /timestamps/regenerate, POST /transcriptions) intentionally block until they have something to return; you don't poll those — you await the single response.

Get a signed POST when a transcription finishes — no polling. Two ways in: a registered webhook (one per API key, fires for every job the key starts) or a per-request callback_url on POST /transcriptions (fires for that one job; see below). Webhook endpoints are API-key only: OAuth bearer tokens (from the MCP connector flow) get 403 forbidden here, but they can still use callback_url.

Events

• transcription.completed — your transcription reached status: completed.
• transcription.failed — your transcription reached status: failed.
• clip.completed / clip.failed: a clip render created with this key finished; data.clip carries a fresh presigned mp4_url on completion.
• webhook.test — you called POST /api/v1/webhooks/test.

Register

curl -X POST https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/transcribe-so/webhook",
    "events": ["transcription.completed", "transcription.failed"]
  }'

events is optional and defaults to all four events (transcription.* and clip.*); unknown names are dropped (an empty result is 400 invalid_request). Registering again replaces the previous webhook on that key. The 201 response is { id, url, events, signing_secret, created_at } with a one-time signing_secret (whsec_…). Store it — we never show it again. You can also register a webhook from the dashboard at /settings/api-keys.

Inspect and remove

# Current webhook on this key (null if none)
curl -sS https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"
# -> { "webhook": { "id", "url", "events", "consecutive_failures", "disabled_at",
#                   "last_delivery_at", "last_success_at", "created_at" } }

# Revoke it
curl -sS -X DELETE https://transcribe.so/api/v1/webhooks \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"
# -> { "revoked": true }

Delivery headers

• Content-Type: application/json
• X-Transcribe-Signature: t=<unix-seconds>,v1=<hex> (see below)
• X-Transcribe-Event: transcription.completed (or transcription.failed, clip.completed, clip.failed, webhook.test)
• User-Agent: transcribe.so-webhook/1

Payload

{
  "id": "evt_1234",
  "event": "transcription.completed",
  "created": 1777472458,
  "data": {
    "transcription": {
      "id": 4821,
      "status": "completed",
      "stage": "completed",
      "pipeline_code": "standard",
      "language": "auto",
      "detected_language": "en",
      "source": "upload",
      "title": "podcast.mp3",
      "duration_seconds": 60,
      "charge_usd": 0.03,
      "error": null,
      "created_at": "2026-04-29T14:20:01.120Z",
      "processing_started_at": "2026-04-29T14:20:05.004Z",
      "completed_at": "2026-04-29T14:25:27.968Z"
    }
  }
}

transcription.failed carries the same shape with status: "failed" and a non-null error. webhook.test sends data: { message, delivered_at } instead.

Fetch the full result (segments, chapters, sections, qna) via GET /api/v1/transcriptions/:id/result?include=all— we don't push the full body inline because it can be large.

Verify the signature

Every delivery carries X-Transcribe-Signature: t=<unix-seconds>,v1=<hex>. The v1 value is hex(hmac_sha256(signing_secret, `$${t}.$${rawBody}`)). Verify on the raw body (re-serializing JSON breaks the HMAC).

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const m = header.match(/t=(\d+),v1=([0-9a-f]+)/);
  if (!m) return false;
  const [, t, v1] = m;
  // Reject if more than 5 minutes off (replay protection).
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === v1.length &&
    timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(v1, "utf8"));
}

import hmac, hashlib, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.match(r"t=(\d+),v1=([0-9a-f]+)", header)
    if not m: return False
    t, v1 = m.group(1), m.group(2)
    if abs(int(time.time()) - int(t)) > 300: return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, v1)

Retry

We retry any non-2xx (or network failure) at 1m, 5m, 30m, 3h, 12h. Five attempts max, 10s HTTP timeout each. After 5 consecutive failures across deliveries, the webhook itself is auto-disabled — re-enable it from the dashboard once your endpoint is healthy. Per-request callbacks have nothing to disable; each one just stops after its 5th attempt.

Per-request callback (callback_url)

Only care about one job, or calling through OAuth / the MCP server where you cannot register a webhook? Pass callback_url on POST /api/v1/transcriptions (or the MCP transcribe tool). The 202 then carries callback: { url, secret }; secret is the whsec_...HMAC key for that transcription's deliveries. It is deterministic per transcription (an idempotent replay returns the same value) and is never returned by GET, so store it.

curl -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "youtube",
    "url": "https://youtu.be/dQw4w9WgXcQ",
    "callback_url": "https://example.com/hooks/transcribe"
  }'
# 202 -> { "id": 4821, "status": "processing", ...,
#          "callback": { "url": "https://example.com/hooks/transcribe",
#                        "secret": "whsec_..." } }

• Same payload, headers and signature scheme as a registered webhook; only transcription.completed and transcription.failed are sent. POST /transcriptions/:id/clips takes a callback_url too (events clip.completed / clip.failed, secret returned as callback_secret).
• Fires in addition to a registered webhook when both apply (two deliveries).
• Must be a public http(s) URL (max 2048 chars). Private, loopback, link-local and internal hosts are rejected with 400 invalid_request, and the target is re-checked right before every POST.
• GET /transcriptions/:id echoes callback_url, never the secret.

Send a test event

curl -X POST https://transcribe.so/api/v1/webhooks/test \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

Enqueues a synthetic webhook.test delivery — useful to confirm your URL is reachable and signature verification works before any real transcriptions run.

Same rates as the dashboard, and no separate API quota or minimums. On subscription plans, transcriptions run on the included unlimited allowance ($0, no wallet hold). On Pay as you go, jobs bill the wallet at $1/hour. Captioned clip renders are a flat $0.05 per started 60 seconds of clip on every plan, billed to the wallet (held at request, settled on completion, released on failure).

Full upload flow with curl. The hardest path — YouTube and external URL skip steps 2-3.

For files over ~50 MB or unstable networks, see the resumable upload recipe instead. Same auth, same continuation step.

# 0. Smoke test
curl -sS https://transcribe.so/api/v1/me \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY"

# 1. Get a presigned upload URL
SIZE=$(stat -f%z podcast.mp3 2>/dev/null || stat -c%s podcast.mp3)
PRESIGN=$(curl -sS -X POST https://transcribe.so/api/v1/uploads \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"filename\": \"podcast.mp3\", \"content_type\": \"audio/mpeg\", \"file_size\": $SIZE }")
UPLOAD_URL=$(echo "$PRESIGN" | jq -r .upload_url)
UPLOAD_ID=$(echo "$PRESIGN" | jq -r .upload_id)

# 2. PUT the file straight to S3
curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @podcast.mp3

# 3. Submit the transcription
DURATION=$(ffprobe -i podcast.mp3 -show_entries format=duration -v quiet -of csv="p=0" | cut -d'.' -f1)
JOB=$(curl -sS -X POST https://transcribe.so/api/v1/transcriptions \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"source\": \"upload\",
    \"upload_id\": \"$UPLOAD_ID\",
    \"original_filename\": \"podcast.mp3\",
    \"duration_seconds\": $DURATION
  }")
TR_ID=$(echo "$JOB" | jq -r .id)

# 4. Wait until done (long-poll, up to 45 s per call; loop while _timed_out)
while true; do
  STATE=$(curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID/wait?timeout=45" \
    -H "Authorization: Bearer $TRANSCRIBE_API_KEY")
  echo "$STATE" | jq -r '"\(.status) · \(.stage)"'
  S=$(echo "$STATE" | jq -r .status)
  [[ "$S" == "completed" || "$S" == "failed" ]] && break
done

# 5. Pull the result (segments are only included when you ask for them)
curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID/result?include=all" \
  -H "Authorization: Bearer $TRANSCRIBE_API_KEY" | jq

Same flow in Python:

import os, time, requests

API = "https://transcribe.so/api/v1"
H = {"Authorization": f"Bearer {os.environ['TRANSCRIBE_API_KEY']}"}

with open("podcast.mp3", "rb") as f:
    body = f.read()

p = requests.post(f"{API}/uploads", headers=H, json={
    "filename": "podcast.mp3",
    "content_type": "audio/mpeg",
    "file_size": len(body),
}).json()

requests.put(p["upload_url"], data=body, headers={"Content-Type": "audio/mpeg"}).raise_for_status()

job = requests.post(f"{API}/transcriptions",
    headers={**H, "Idempotency-Key": "podcast-149"},
    json={
        "source": "upload",
        "upload_id": p["upload_id"],
        "original_filename": "podcast.mp3",
        "duration_seconds": 60,
    },
).json()

while True:
    state = requests.get(f"{API}/transcriptions/{job['id']}/wait", headers=H,
                         params={"timeout": 45}).json()
    if state["status"] in ("completed", "failed"):
        break

# Default include is chapters,sections,qna; ask for everything explicitly.
result = requests.get(f"{API}/transcriptions/{job['id']}/result", headers=H,
                      params={"include": "all"}).json()
print(f"segments={len(result['segments'])} chapters={len(result['chapters'])} sections={len(result['sections'])}")

Live speech-to-text over a WebSocket. The REST trio below mints a session and a short-lived ticket; the audio itself streams to ws_url. Sessions hold a 60-minute wallet quote up front (402 insufficient_funds if the wallet is short), allow one active session per user, and are gated behind the realtime pipeline (400 unsupported_pipeline when your plan doesn't include it). Not exposed over MCP.

{
  "session_id": "rts_0123456789abcdef",
  "transcription_id": 4822,
  "ws_url": "wss://api.transcribe.so/v1/realtime",
  "ticket": "…",
  "cap_minutes": 60,
  "language": "auto"
}

The same API is exposed as tools over the Model Context Protocol at https://transcribe.so/mcp (Streamable HTTP, stateless, POST-only). Auth is identical: send Authorization: Bearer tsk_live_…, or let the client run the OAuth 2.0 authorization-code + PKCE flow it discovers via /.well-known/oauth-protected-resource. Rate limit is shared with /api/v1 (60 requests / minute).

Connect

• Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector → URL https://transcribe.so/mcp. Sign in when prompted (OAuth), or paste an API key as the Authorization header where the client supports it.
• Claude Code: claude mcp add --transport http transcribe https://transcribe.so/mcp, then /mcp to authenticate.
• ChatGPT: Settings → Connectors → Developer mode → add https://transcribe.so/mcp. The read-only search and fetch tools follow the ChatGPT connector contract, so the server also works for chat search and deep research.
• Anything else: any MCP client that speaks Streamable HTTP. Tool schemas come from tools/list; discovery hints at /.well-known/mcp/server-card.json and /.well-known/mcp/server.json.

Tools

Every tool declares MCP annotations (title, readOnlyHint, destructiveHint) and returns one JSON text block plus structuredContent. Errors use the same { error: { code, message, request_id, doc_url } } envelope as REST. Registered webhooks, realtime sessions, tus uploads and addons are REST-only; the transcribe tool accepts callback_url for per-job notifications.

OAuth details

• Authorization server metadata: /.well-known/oauth-authorization-server (authorization code + PKCE S256, refresh tokens, dynamic client registration).
• Protected resource metadata: /.well-known/oauth-protected-resource (resource https://transcribe.so/mcp). Unauthenticated /mcp calls return 401 with a WWW-Authenticate header pointing there.
• OAuth tokens are rate-limited per user rather than per key and cannot manage webhooks. Plain-text guide for agents: /auth.md.

@transcribe-so/remotion (in the repo at packages/remotion/, private for now, zero runtime deps) wraps /words and /subtitles for Remotion projects: wordsToCaptions() maps the full word list (all: true) to @remotion/captions Caption[] (one caption per word, leading space on every token except the first, timestampMs = start_ms), chaptersToSequences() turns chapters into <Sequence> props, and useTranscribeWords() is a delayRender-aware hook for the case where the fetch has to happen inside the composition (returns status, words, captions, available, reason, error).

// Root.tsx: fetch outside the composition, pass words in as props
import { createClient } from '@transcribe-so/remotion'

export const calculateMetadata = async ({ props }) => {
  const client = createClient({ apiKey: process.env.TRANSCRIBE_API_KEY! })
  const { words } = await client.getWords(props.id, { all: true })
  return { props: { ...props, words } }
}

// TikTokCaptions.tsx: no fetch, no process.env
import { createTikTokStyleCaptions } from '@remotion/captions'
import { frameToMs, wordsToCaptions } from '@transcribe-so/remotion'
import type { TranscribeWord } from '@transcribe-so/remotion'
import { AbsoluteFill, useCurrentFrame, useVideoConfig } from 'remotion'
import { useMemo } from 'react'

export const TikTokCaptions: React.FC<{ id: number; words: TranscribeWord[] }> = ({ words }) => {
  const nowMs = frameToMs(useCurrentFrame(), useVideoConfig().fps)
  const { pages } = useMemo(
    () => createTikTokStyleCaptions({ captions: wordsToCaptions(words), combineTokensWithinMilliseconds: 1200 }),
    [words],
  )
  const page = pages.find((p) => nowMs >= p.startMs && nowMs < p.startMs + p.durationMs)
  return (
    <AbsoluteFill style={{ justifyContent: 'flex-end', alignItems: 'center', paddingBottom: 120 }}>
      <div style={{ fontSize: 64, color: 'white' }}>{page?.text}</div>
    </AbsoluteFill>
  )
}

Word timings exist only for word-timestamp pipelines: check available on /words first. Fetch in a script or calculateMetadata and pass words via inputProps; never read the API key from process.env inside a composition or bundle it into a public one. Full README, karaoke and chapters snippets: packages/remotion/README.md; a fetch-to-render recipe is in the cookbook.