Upload a file

Request format

The file is the request body — no multipart forms, no JSON wrapping, no chunk protocol:

Query parameters

All optional:

Supported languages

auto (default — the language is detected from the audio) or one of:

en, es, ru, zh, hi, ar, pt, bn, fr, de, ja, ko, tr, it, vi, pl, uk, nl, id, th, fa, sv, cs, ro, el, hu, da, fi, no, sk, he, ms, bg, hr, sr, sl, lt, lv, et, ta, te, mr, ur, sw, ml, kn, gu, pa, my, ne, si, km, lo, az, kk, uz, ka, hy, sq, bs, mk, is, mn, tg, tk, tt, ca, eu, gl, cy, af, tl, jw, su, yo, ha, so, am, sn, mg, ln, mt, lb, oc, br, nn, fo, sd, ps, ht, mi, haw, yi, ba, be, as, bo, sa, la

Two-letter ISO 639-1 codes (plus haw and jw). An unsupported value returns 422.

Request

curl -X POST "https://app.specala.ai/api/v1/developer/transcriptions?language=en" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H 'Content-Disposition: attachment; filename="standup.mp3"' \
  --data-binary @standup.mp3

import httpx

with open("standup.mp3", "rb") as f:
    resp = httpx.post(
        "https://app.specala.ai/api/v1/developer/transcriptions",
        params={"language": "en"},
        headers={
            "Authorization": "Bearer sk_live_your_key_here",
            "Content-Disposition": 'attachment; filename="standup.mp3"',
        },
        content=f,        # streamed from disk — works for 2 GB files too
        timeout=httpx.Timeout(10, write=None),  # don't time out mid-upload
    )
resp.raise_for_status()
t = resp.json()
print(t["uuid"], t["status"])   # "3fa85f64-…" "queued"

import { openAsBlob } from "node:fs"; // Node 20+

const res = await fetch(
  "https://app.specala.ai/api/v1/developer/transcriptions?language=en",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_your_key_here",
      "Content-Disposition": 'attachment; filename="standup.mp3"',
    },
    body: await openAsBlob("standup.mp3"), // streamed, Content-Length set for you
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const t = await res.json();
console.log(t.uuid, t.status); // "3fa85f64-…" "queued"

Response

201 Created — the file was received and queued. Transcription happens asynchronously.

{
  "id": 12345,
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued"
}

Status lifecycle & polling

Poll GET /transcriptions/{uuid} every 5–10 seconds until a terminal status:

import time

while True:
    t = httpx.get(f"{BASE}/transcriptions/{uuid}", headers=HEADERS).json()
    if t["status"] in ("completed", "failed", "insufficient_balance"):
        break
    time.sleep(10)

Common error_code values on failed:

Limits & billing

Anti-abuse safeguards (per-key daily caps, concurrent-upload limits) sit far above normal usage — if you hit 429 with upload_quota_exceeded, contact support to raise them.

Retries

Without precautions, retrying an upload whose response you never saw (connection dropped after the last byte) would create a second transcription and a second charge. The Idempotency-Key header solves this:

• Send a unique value per file (a UUID is perfect) with every attempt.
• If the file was already accepted under that key, you get 200 with the original uuid instead of a duplicate — no double billing, quotas untouched.
• A request with the same key still in flight returns 409 idempotency_conflict — wait Retry-After and retry.
• Add jitter: sleep a random slice of Retry-After rather than the exact value. When many clients are throttled at once, waking them all on the same second just recreates the queue.
• Only success is remembered (for 24 hours); after a failed attempt the key is free to reuse.

curl -X POST "https://app.specala.ai/api/v1/developer/transcriptions" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H 'Content-Disposition: attachment; filename="standup.mp3"' \
  -H "Idempotency-Key: 7f3a2b1c-9d4e-4f5a-8b6c-1d2e3f4a5b6c" \
  --data-binary @standup.mp3

Errors

See Errors for the full reference and retry guidance.