# Transcribe7 API — complete reference (for developers and AI coding assistants) > Speech-to-text API: real-time transcription over WebSocket and async file transcription over REST, with speaker > diarization, per-token language identification and one-way / two-way translation. Billed per second of audio > (EUR 2 per audio hour) from prepaid credit. Follows common STT REST + WebSocket conventions. This single file is the whole reference. If you are an AI assistant integrating this API, read it end to end before writing code, and follow "Integration rules" at the bottom. - REST base URL: `https://api.transcribe7.com/v1` - Real-time WebSocket: `wss://api.transcribe7.com/transcribe-websocket` - Human docs: https://api.transcribe7.com/docs/ - Developer platform (keys, usage, credit, team): https://platform.transcribe7.com - Support: support@transcribe7.com --- ## 1. Authentication Every request needs an API key: `Authorization: Bearer t7_live_...` - `t7_live_...` keys are secret. Use them only on servers. Store them in an environment variable (recommended name: `T7_API_KEY`). Never put them in browser code, mobile apps, git or logs. - Browsers and mobile apps use temporary keys `t7_temp_...` created by your backend (section 5). - Keys are created at https://platform.transcribe7.com → API keys. Each key belongs to a project. ## 2. Billing and limits (what can make requests fail) - Prepaid credit. Price: EUR 2 per hour of audio, billed per second. Real-time, files and translation cost the same. - A real-time stream or a transcription needs credit to START. A real-time stream ends with error `account_balance_exhausted` (402) when the credit it may use runs out. Each open file transcription holds 1 hour of credit until its real length is known. - Per-account limits: concurrent real-time streams (default 10), pending transcriptions (default 10), stored files (200 files / 20 GB), request rate (about 600 requests/min per key). Exceeding them returns 429 `limit_exceeded` (respect the `Retry-After` header). - Retention: uploaded files are deleted 24 hours after upload; transcriptions (and transcripts) 24 hours after they finish. Real-time audio and text are never stored. Fetch results within 24 hours. ## 3. Errors REST errors (JSON, with the HTTP status): ```json {"status_code": 400, "error_type": "invalid_request", "message": "...", "validation_errors": [{"error_type": "missing", "location": "body.model", "message": "Field required"}], "request_id": "...", "more_info": "https://api.transcribe7.com/docs/#errors"} ``` WebSocket errors arrive as a text message, then the server closes the connection: ```json {"error_code": 401, "error_type": "unauthenticated", "error_message": "Incorrect API key provided.", "request_id": "..."} ``` | HTTP | error_type | What to do | |---|---|---| | 400 | invalid_request, invalid_cursor, model/audio specific types | Fix the request (see validation_errors). Don't retry unchanged. | | 401 | unauthenticated | Wrong/revoked key. Don't retry. | | 402 | account_balance_exhausted | No credit. Tell the user to top up at platform.transcribe7.com/billing. | | 402 | account_budget_exhausted | Monthly allowance used. Contact support. | | 404 | file_not_found, transcription_not_found | Wrong id, or deleted (24 h retention). | | 409 | transcription_invalid_state | E.g. transcript requested before status is completed. Keep polling. | | 413 | file_too_large (max 1 GB), max_duration_reached (WebSocket) | Split the audio / open a new stream. | | 429 | limit_exceeded | Wait `Retry-After` seconds, then retry with backoff. | | 503/504 | service_unavailable | Temporary. Retry with exponential backoff (e.g. 1 s, 2 s, 4 s, max 5 tries). | Always log `request_id`. ## 4. Real-time transcription (WebSocket) URL: `wss://api.transcribe7.com/transcribe-websocket` Authentication — choose one: - Server: HTTP header `Authorization: Bearer t7_live_...` on the WebSocket upgrade. - Browser: protocols list `new WebSocket(url, ["t7-api-key", temporaryKey])`. - (Also accepted: `"api_key"` inside the start message.) A wrong key does not fail the handshake: the socket opens, an error message arrives, then it closes. Protocol: 1. Send the start message (JSON text) first. 2. Stream audio as binary messages in real time (e.g. 100 ms chunks). Do not send faster than real time. 3. Optional control messages (text): `{"type": "finalize"}` (finalize pending tokens now), `{"type": "keepalive"}` (send at least every 20 s when no audio flows). 4. End of audio: send an EMPTY binary message. Remaining tokens arrive, then `{"finished": true}`, then the server closes. ### Start message fields | Field | Type | Notes | |---|---|---| | model | string | Real-time model, e.g. `stt-rt-v6`. List: GET /v1/models. | | audio_format | string | `auto` (aac, aiff, amr, asf, flac, mp3, ogg, wav, webm) or raw: `pcm_s16le`, `pcm_f32le`, `mulaw`, `alaw`, ... | | sample_rate | int | Required for raw formats, e.g. 16000. | | num_channels | int | Required for raw formats, 1 or 2. | | language_hints | string[] | Expected languages, e.g. `["sl","en"]`. Improves accuracy. | | language_hints_strict | bool | Rely more on the hints. | | enable_language_identification | bool | Adds `language` to each token. | | enable_speaker_diarization | bool | Adds `speaker` to each token. | | enable_endpoint_detection | bool | Finalizes when the speaker stops and emits an `` token. | | endpoint_sensitivity, max_endpoint_delay_ms, endpoint_latency_adjustment_level | | Endpoint tuning. | | translation | object | `{"type":"one_way","target_language":"en"}` or `{"type":"two_way","language_a":"sl","language_b":"en"}` | | context | object | `{"general":[{"key":"Domain","value":"medicine"}],"text":"...","terms":["Transcribe7"],"translation_terms":[{"source":"...","target":"..."}]}` | | client_reference_id | string | Your tracking id (max 256). | ### Responses ```json {"tokens": [{"text": "How", "start_ms": 600, "end_ms": 760, "confidence": 0.97, "is_final": true, "speaker": "1", "language": "en", "translation_status": "original"}], "final_audio_proc_ms": 760, "total_audio_proc_ms": 1250} ``` ```json {"tokens": [], "finished": true} ``` Rules for rendering text: - Tokens are pieces of words INCLUDING their spaces — concatenate `text` without adding separators. - `is_final: true` tokens never change and are sent once: append them to your final transcript. - `is_final: false` tokens are provisional and are re-sent in every message until final: on each message, REPLACE the previous provisional text with the new provisional tokens. - With translation, `translation_status` is `"original"` or `"translation"` — keep two separate texts. - Special tokens: `` (endpoint detected), `` (after finalize). Don't display them. ### Example — Node.js server (npm i ws) ```js import WebSocket from "ws"; import fs from "fs"; const ws = new WebSocket("wss://api.transcribe7.com/transcribe-websocket", { headers: { Authorization: `Bearer ${process.env.T7_API_KEY}` }, }); let finalText = ""; ws.on("open", () => { ws.send(JSON.stringify({ model: "stt-rt-v6", audio_format: "pcm_s16le", sample_rate: 16000, num_channels: 1, language_hints: ["en"], enable_speaker_diarization: true, })); const pcm = fs.readFileSync("audio.raw"); // 16 kHz mono s16le let i = 0; const timer = setInterval(() => { if (i >= pcm.length) { clearInterval(timer); ws.send(Buffer.alloc(0)); return; } // empty = end of audio ws.send(pcm.subarray(i, (i += 3200))); // 100 ms }, 100); }); ws.on("message", (data) => { const res = JSON.parse(data.toString()); if (res.error_code) { console.error(res.error_type, res.error_message, res.request_id); return; } let provisional = ""; for (const t of res.tokens ?? []) { if (t.text === "" || t.text === "") continue; if (t.is_final) finalText += t.text; else provisional += t.text; } process.stdout.write(`\r${finalText}${provisional}`); if (res.finished) console.log("\n[done]"); }); ``` ### Example — Python server (pip install websockets) ```python import asyncio, json, os, websockets async def main(): async with websockets.connect( "wss://api.transcribe7.com/transcribe-websocket", additional_headers={"Authorization": f"Bearer {os.environ['T7_API_KEY']}"}, ) as ws: await ws.send(json.dumps({"model": "stt-rt-v6", "audio_format": "auto", "language_hints": ["en"]})) async def send_audio(): with open("audio.mp3", "rb") as f: while chunk := f.read(4096): await ws.send(chunk) await asyncio.sleep(0.05) await ws.send(b"") # end of audio sender = asyncio.create_task(send_audio()) final = "" async for message in ws: res = json.loads(message) if res.get("error_code"): raise RuntimeError(f"{res['error_type']}: {res['error_message']}") final += "".join(t["text"] for t in res.get("tokens", []) if t.get("is_final") and t["text"] not in ("", "")) if res.get("finished"): break await sender print(final) asyncio.run(main()) ``` ### Example — browser (with a temporary key from your backend) ```js const { api_key } = await (await fetch("/my-backend/t7-temp-key", { method: "POST" })).json(); const ws = new WebSocket("wss://api.transcribe7.com/transcribe-websocket", ["t7-api-key", api_key]); ws.onopen = async () => { ws.send(JSON.stringify({ model: "stt-rt-v6", audio_format: "auto", language_hints: ["en"] })); const stream = await navigator.mediaDevices.getUserMedia({ audio: true }); const rec = new MediaRecorder(stream, { mimeType: "audio/webm" }); rec.ondataavailable = (e) => e.data.size && ws.readyState === 1 && ws.send(e.data); rec.onstop = () => ws.send(new ArrayBuffer(0)); // end of audio rec.start(250); }; ws.onmessage = (e) => { /* same token handling as above */ }; ``` ## 5. Temporary keys (for browsers and mobile apps) `POST /v1/auth/temporary-api-key` — call from YOUR backend with your secret key; return only `api_key` to the client. Request: ```json {"usage_type": "transcribe_websocket", "expires_in_seconds": 60, "single_use": true, "max_session_duration_seconds": 3600, "client_reference_id": "user-123"} ``` - `usage_type` (required): `transcribe_websocket`. - `expires_in_seconds` (required, 1–3600): how long the key can be used to OPEN streams. - `single_use`: the key opens at most one stream (recommended). - `max_session_duration_seconds`: caps each stream opened with the key. - `client_reference_id`: bound to the key, max 256. Response `201`: ```json {"api_key": "t7_temp_...", "expires_at": "2026-11-13T10:01:00.000Z"} ``` ## 6. Async file transcription (REST) Flow: upload a file (or use a public URL) → create a transcription → wait (poll or webhook) → fetch the transcript → (optionally) delete. ### Files - `POST /v1/files` — multipart/form-data, field `file` (audio or video, max 1 GB), optional field `client_reference_id`. → `201 {"id","filename","size","created_at","client_reference_id"}` - `GET /v1/files?limit=100&cursor=...` → `{"files":[...], "next_page_cursor": "..." | null}` (newest first, limit 1–1000) - `GET /v1/files/count` → `{"playground":0,"public_api":N,"total":N}` - `GET /v1/files/{id}` → file object - `DELETE /v1/files/{id}` → `204` ### Transcriptions `POST /v1/transcriptions` → `201` transcription object. Body (JSON): | Field | Notes | |---|---| | model (required) | Async model, e.g. `stt-async-v6`. List: GET /v1/models. | | file_id or audio_url | Exactly one: an uploaded file id, or a public http(s) URL. | | language_hints, language_hints_strict, enable_language_identification, enable_speaker_diarization, translation, context | As in real-time. | | webhook_url | Public URL we POST to when it finishes. | | webhook_auth_header_name / webhook_auth_header_value | A header we add to the webhook (e.g. `Authorization` / `Bearer ...`). | | client_reference_id | Your tracking id (max 256). | Transcription object: ```json {"id": "548d023b-...", "status": "queued", "created_at": "...", "model": "stt-async-v6", "audio_url": null, "file_id": "84c32fc6-...", "filename": "meeting.m4a", "language_hints": ["en"], "enable_speaker_diarization": true, "enable_language_identification": true, "audio_duration_ms": null, "error_type": null, "error_message": null, "webhook_url": null, "webhook_auth_header_name": null, "webhook_auth_header_value": null, "webhook_status_code": null, "client_reference_id": "order-42"} ``` Status: `queued` → `processing` → `completed` | `error`. - `GET /v1/transcriptions/{id}` — poll every 2–5 seconds (or use a webhook). - `GET /v1/transcriptions?limit=&cursor=` → `{"transcriptions":[...], "next_page_cursor": ...}` - `GET /v1/transcriptions/count` - `DELETE /v1/transcriptions/{id}` → `204` (`409` while still processing) ### Transcript `GET /v1/transcriptions/{id}/transcript` (only when `status` is `completed`): ```json {"id": "548d023b-...", "text": "Hello everyone...", "tokens": [{"text": "Hel", "start_ms": 0, "end_ms": 180, "confidence": 0.98, "speaker": "1", "language": "en", "translation_status": "original"}]} ``` With translation, `tokens` contains both original and translated tokens (see `translation_status`). ### Webhooks When `webhook_url` is set, we POST `{"id": "...", "status": "completed" | "error"}` when the transcription finishes (3 attempts), with your auth header if configured. Respond 2xx quickly, then fetch the transcript. The URL must be public; add your own query parameters to identify the job. ### Example — curl ```bash # upload FILE_ID=$(curl -s https://api.transcribe7.com/v1/files -H "Authorization: Bearer $T7_API_KEY" -F file=@meeting.m4a | jq -r .id) # create TR_ID=$(curl -s https://api.transcribe7.com/v1/transcriptions -H "Authorization: Bearer $T7_API_KEY" -H "Content-Type: application/json" \ -d "{\"model\":\"stt-async-v6\",\"file_id\":\"$FILE_ID\",\"enable_speaker_diarization\":true}" | jq -r .id) # poll until [ "$(curl -s https://api.transcribe7.com/v1/transcriptions/$TR_ID -H "Authorization: Bearer $T7_API_KEY" | jq -r .status)" = "completed" ]; do sleep 3; done # result curl -s https://api.transcribe7.com/v1/transcriptions/$TR_ID/transcript -H "Authorization: Bearer $T7_API_KEY" | jq -r .text ``` ### Example — Python (requests) ```python import os, time, requests API = "https://api.transcribe7.com/v1" H = {"Authorization": f"Bearer {os.environ['T7_API_KEY']}"} def transcribe(path: str) -> dict: with open(path, "rb") as f: file_id = requests.post(f"{API}/files", headers=H, files={"file": f}).json()["id"] tr = requests.post(f"{API}/transcriptions", headers=H, json={ "model": "stt-async-v6", "file_id": file_id, "enable_speaker_diarization": True, }) tr.raise_for_status() tid = tr.json()["id"] while True: st = requests.get(f"{API}/transcriptions/{tid}", headers=H).json() if st["status"] == "completed": break if st["status"] == "error": raise RuntimeError(st["error_message"]) time.sleep(3) transcript = requests.get(f"{API}/transcriptions/{tid}/transcript", headers=H).json() requests.delete(f"{API}/transcriptions/{tid}", headers=H) # optional cleanup requests.delete(f"{API}/files/{file_id}", headers=H) return transcript ``` ### Example — C# (.NET) ```csharp using System.Net.Http.Headers; using System.Net.Http.Json; using System.Text.Json; var http = new HttpClient { BaseAddress = new Uri("https://api.transcribe7.com/v1/") }; http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("T7_API_KEY")); using var form = new MultipartFormDataContent { { new StreamContent(File.OpenRead("meeting.m4a")), "file", "meeting.m4a" } }; var file = await (await http.PostAsync("files", form)).Content.ReadFromJsonAsync(); var create = await http.PostAsJsonAsync("transcriptions", new { model = "stt-async-v6", file_id = file.GetProperty("id").GetString(), enable_speaker_diarization = true }); create.EnsureSuccessStatusCode(); var id = (await create.Content.ReadFromJsonAsync()).GetProperty("id").GetString(); string status; do { await Task.Delay(3000); status = (await http.GetFromJsonAsync($"transcriptions/{id}")).GetProperty("status").GetString()!; } while (status is "queued" or "processing"); var transcript = await http.GetFromJsonAsync($"transcriptions/{id}/transcript"); Console.WriteLine(transcript.GetProperty("text").GetString()); ``` ## 7. Other endpoints - `GET /v1/models` — available models (real-time and async), languages, translation support. - `GET /v1/usage?month=2026-11` — your usage: `{"month","realtime_seconds","async_seconds","total_seconds","monthly_cap_seconds","daily":[{"date","realtime_seconds","async_seconds","realtime_sessions","transcriptions"}]}` ## 8. Integration rules (for AI assistants and developers) 1. Read the key from an environment variable (`T7_API_KEY`). Never hard-code it, never send it to a browser or app. 2. Browser / mobile real-time: add a backend endpoint that calls `POST /v1/auth/temporary-api-key` (single_use: true, expires_in_seconds: 60) and returns only `api_key`; the client connects with `["t7-api-key", key]`. 3. Stream audio at real-time speed; end with an empty binary message; wait for `{"finished": true}`. 4. Render tokens correctly: append final tokens, replace provisional ones on every message, hide `` / ``. 5. Handle errors by `error_type`: retry only 429 (after Retry-After) and 503/504 (exponential backoff); surface `account_balance_exhausted` to the user with a link to https://platform.transcribe7.com/billing. 6. Async: prefer webhooks; if polling, every 2–5 s with a timeout. Fetch transcripts within 24 hours. 7. Pass `client_reference_id` (your job / user id) so usage can be traced. 8. Delete files and transcriptions you no longer need (they are removed after 24 h anyway). 9. Test with a short clip first; check `request_id` in any error and log it.