Upload a file

Request

The smallest call that works: a key, a filename and the bytes. Every header is listed under Request format, the optional switches under Query parameters.

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.

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "reports": []
}

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:

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.

Your own identifiers

A transcription almost always belongs to something in your system: a deal, a call, a ticket. Send your own identifier with the upload and get it back everywhere, instead of keeping a table mapping our id to yours.

curl -X POST 'https://app.specala.ai/api/v1/developer/transcriptions' \
  -H 'Authorization: Bearer sk_live_your_key_here' \
  -H 'Content-Disposition: attachment; filename="call.mp3"' \
  -H 'X-External-Id: deal-A-1043' \
  -H 'X-Metadata: {"crm":"hubspot","owner_id":17,"queue":"sales"}' \
  --data-binary @call.mp3

Both headers are optional and independent — send one without the other if that is all you need.

What you can send

Anything that does not fit is refused at upload with 422, and the code in the response says what was wrong: external_id_too_long, metadata_too_deep, metadata_value_invalid, and so on. Nothing is silently truncated or dropped.

What comes back

Both fields appear in GET /transcriptions/{id} and in every list item:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "deal-A-1043",
  "metadata": { "crm": "hubspot", "owner_id": 17, "queue": "sales" },
  "status": "completed"
}

For transcriptions that did not come through the API both are null. That is not an error.

Searching by your own identifiers

You never need our id to find a recording — the list filters on your values.

GET /transcriptions?external_id=deal-A-1043
GET /transcriptions?metadata.queue=sales

Matching is exact and one key at a time; this is not a full-text search. The filters combine with the rest, e.g. ?metadata.queue=sales&status=completed.

One identifier across several transcriptions

X-External-Id does not have to be unique. A deal usually means several calls, and all of them may carry the same deal-A-1043 — in which case ?external_id=deal-A-1043 returns all of them.

If you need protection against uploading the same file twice, that is what Idempotency-Key is for, with a 24-hour window — see Retries.

Assigning an author

By default a transcription uploaded through the API belongs to the person who created the key. For a team that is rarely right: a CRM or telephony integration uploads calls made by different managers, and each of them should see their own calls under "My meetings", get the "ready" notification and show up in per-person reports.

Send the owner in the X-Author header. The value is typed — <type>:<value>:

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="call-1043.mp3"' \
  -H 'X-Author: email:alex@company.com' \
  -H 'X-External-Id: deal-A-1043' \
  --data-binary @call-1043.mp3

What the author gets and what stays with the key:

• The transcription is the author's: it is in their list, they get notified when it is ready, and it counts as theirs in team reports. Every response returns the owner as author: { id, email, name }.
• Permissions, limits and billing are the key's. The project you attach to must be one the key's creator can upload to; minutes are charged to the workspace as usual.
• The author does not have to be a member of the project you attach to. They will still see the transcription — it is theirs — and an admin can add them to the project later. Uploads are never rejected for this, so automations keep working.

If the author cannot be found, the upload is rejected with 422 author_not_member and nothing is charged — there is no silent fallback to the key's creator, because a mis-attributed call is harder to notice than a failed one. The same code is returned whether the email is unknown to us or belongs to someone outside your workspace. Invite the person to the workspace, or upload without X-Author and assign the author later.

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

Limits & billing

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

Errors

See Errors for the full reference and retry guidance.