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",
    "pipeline_code": "qwen3-asr-flash-filetrans"
  }'

You'll get an integer id back. Poll GET /api/v1/transcriptions/<id> until status is completed, then fetch /result. Or register a webhook (see below) and we'll POST you when it's done.

• 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. Wallet drains monthly credit first, then top-up balance.

The API uses Bearer tokens — no OAuth, no JWT, no cookies. Treat a key like a password.

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 remaining monthly credit.

Limits

• 20 active keys per user
• 60 requests / minute per key
• Wallet itself is the spend cap; no separate per-key cap in v1

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

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: 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.
• 400 / 401 / 404: don't retry; fix the request.

POST endpoints accept an Idempotency-Key header. 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; 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. One webhook per API key.

Events

• transcription.completed — your transcription reached status: completed.
• transcription.failed — your transcription reached status: failed.
• 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" }'

Returns the webhook id and a one-time signing_secret. Store it — we never show it again. You can also register a webhook from the dashboard at /settings/api-keys.

Payload

{
  "id": "evt_1234",
  "event": "transcription.completed",
  "created": 1777472458,
  "data": {
    "transcription": {
      "id": 4821,
      "status": "completed",
      "stage": "completed",
      "pipeline_code": "qwen3-asr-flash-filetrans",
      "language": "auto",
      "source": "upload",
      "title": "podcast.mp3",
      "duration_seconds": 60,
      "billed_seconds": 60,
      "charge_usd": 0.03,
      "completed_at": "2026-04-29T14:25:27.968Z"
    }
  }
}

Fetch the full result (segments, chapters, sections, qna) via GET /api/v1/transcriptions/:id/result — 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.

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 per-minute rates as the dashboard. Billed against your wallet — monthly credit first, then top-up balance. No separate API quota, no minimums.

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,
    \"pipeline_code\": \"qwen3-asr-flash-filetrans\"
  }")
TR_ID=$(echo "$JOB" | jq -r .id)

# 4. Poll until done
while true; do
  STATE=$(curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID" \
    -H "Authorization: Bearer $TRANSCRIBE_API_KEY")
  echo "$STATE" | jq -r '"\(.status) · \(.stage)"'
  S=$(echo "$STATE" | jq -r .status)
  [[ "$S" == "completed" || "$S" == "failed" ]] && break
  sleep 5
done

# 5. Pull the result
curl -sS "https://transcribe.so/api/v1/transcriptions/$TR_ID/result" \
  -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,
        "pipeline_code": "qwen3-asr-flash-filetrans",
    },
).json()

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

result = requests.get(f"{API}/transcriptions/{job['id']}/result", headers=H).json()
print(f"segments={len(result['segments'])} chapters={len(result['chapters'])} sections={len(result['sections'])}")