Transcription

Two ways in — upload-and-transcribe in one call for short audio, or a three-call chunked upload for anything longer — plus list, get, delete, and retry. Everything is workspace-scoped and kept — a failed provider call never loses the audio, it just leaves the transcript row failed with a retry URL.

Session or key — a key credential must include the transcription service (see Authentication).

multipart/form-data with a file field (required) plus optional fields: name (display name, defaults to the filename), language (a BCP-47 tag like en or en-US, default en), and diarize ("true" or "false", default true). Responds 201 with the full Transcript JSON on success.

Audio is capped at 4 MB per file on transcribe, enforced app-side. Netlify's synchronous functions cap request bodies at 6 MB (about 4.5 MB once you account for binary-to-base64 overhead) and run for at most 10 seconds — 4 MB stays comfortably inside both limits with room for the multipart envelope and the provider round trip. Record a shorter clip or lower the bitrate to fit under it, or use chunked upload below for anything longer.

The 4 MB cap is only half of why transcribe is bounded — the other half is that Netlify's synchronous functions are killed at 10 seconds, and a 30-minute file takes the provider roughly a minute to transcribe. Chunking the upload alone doesn't fix that second bound, so long audio needs both a way past the body limit and a way past the timeout: a three-call chunked upload past the first, and a background job — off the request path entirely — past the second.

The client splits the finished audio file into fixed-size byte ranges — not audio segments — and sends them in three calls:

1. POST /api/v1/uploads/chunked (Content-Type: application/json — a namespace of its own, deliberately not on /api/v1/uploads, which is the first-party multipart asset upload) with filename, contentType, totalBytes, partCount, and a lowercase-hex sha256 of the whole file. Returns 201 with uploadId and an expiresAt one hour out.
2. PUT /api/v1/uploads/chunked/:uploadId/parts/:index — raw application/octet-stream bytes for that range, in any order. Re-sending an index overwrites it, so retrying a dropped part is just re-sending it.
3. POST /api/v1/uploads/chunked/:uploadId/complete — Cubster concatenates every part in order and verifies the reassembled file's SHA-256 against the digest sent in step 1, so the file the provider transcribes is guaranteed byte-identical to the one the client split — one whole file, never a stitched-together approximation, which is why diarization stays global and the timeline has no seams at the part boundaries. Responds 202 immediately with a pending transcript — it does not wait for the provider.

From there, poll GET /api/v1/transcripts/:id — the same endpoint below — until status leaves pending. An upload session lives for one hour, and the whole file is capped at 64 MB total (roughly three hours at 48 kbps) — well past that expiry or cap and the begin/complete calls start returning 410/413. POST /api/v1/transcribe above is unchanged and still the right call for anything under 4 MB — chunked upload is strictly for audio that doesn't fit there.

Every failure mode gets its own status and a specific message. A provider failure (422/500/502/503/504) still keeps the uploaded audio — the response body carries { error, transcript: { id, status: "failed", assetId, retryUrl } }, so you can retry without re-uploading.

GET /api/v1/transcripts — list, newest first. Returns { transcripts: [...] }, where each item is the list-view shape (below). Query: limit (max 100) and status (pending, completed, or failed).

GET /api/v1/transcripts/:id — detail, including words. DELETE /api/v1/transcripts/:id — deletes the transcript row and its audio asset (row + blob) together. Either way, an id from another workspace — or a non-UUID — resolves to a plain 404, never a 403.

POST /api/v1/transcripts/:id/retry — re-runs transcription for a pending or failed transcript, reusing the audio already stored — no re-upload. A completed transcript responds 409 { "error": "Transcript is already completed" }.

Public, by opaque key (no listing endpoint — the key is unguessable). Served inline (Content-Disposition: inline) with HTTP Range support (Accept-Ranges: bytes), so an <audio> element can play and seek it directly — Safari in particular won't play at all without Range support. A single Range: bytes=a-b request returns 206 with Content-Range; malformed or unsatisfiable ranges get 416. Responses are never cached (Cache-Control: private, no-store) — deleting a transcript revokes its audio immediately.

The durable artifact returned by transcribe, transcripts.get, and a successful retry. speaker is an integer index (0, 1, …) or null — never a name; naming speakers is downstream's job. List responses (GET /api/v1/transcripts) omit text/segments/words and add a preview (first 200 characters of text) instead; detail responses (GET /api/v1/transcripts/:id, and the response from transcribe/retry) include words.

A transcript's source.kind isn't always "upload" — a transcript can also come from a live realtime voice session (source.kind: "live"), which has no audio asset at all.

client.transcribe() mirrors uploads.upload() — even on a provider failure it never throws away the file. A failed attempt throws a CubsterError whose transcriptFailure() carries { id, status, assetId, retryUrl } for transcripts.retry. transcripts.get/delete/retry accept an optional { workspace } scope, same as assets.get/update/delete.

cubster transcribe <path> rejects an oversized file locally, before uploading anything. On failure it prints a retry hint with the transcript id.