Transcribe7 API
Speech-to-text for your apps: real-time (WebSocket) and async (files), with speaker diarization, language identification, translation (one-way and two-way) and context. The API follows the widely used STT REST + WebSocket conventions, so existing clients usually only need a new base URL and key.
| REST base URL | https://api.transcribe7.com/v1 |
|---|---|
| WebSocket URL | wss://api.transcribe7.com/transcribe-websocket |
| API keys | t7_live_β¦ (servers) Β· t7_temp_β¦ (temporary, for browsers / apps) |
https://api.transcribe7.com/llms-full.txt β the complete reference in one Markdown file
(also: llms.txt Β· instructions for AI assistants).
Introduction
- Real-time: open a WebSocket, send a start message, stream audio, receive tokens as they are recognised.
- Async: upload a file (or pass a URL), create a transcription, poll or receive a webhook, fetch the transcript.
- Billing is per second of audio processed.
Authentication
Authorization: Bearer t7_live_β¦
Keep t7_live_ keys on your servers. Browsers and mobile apps use a temporary key created by your backend.
Errors & limits
REST errors:
{"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 message, then the connection closes:
{"error_code":401,"error_type":"unauthenticated","error_message":"Incorrect API key provided.","request_id":"β¦"}
| Status | error_type |
|---|---|
| 400 | invalid_request, invalid_cursor, and model / audio specific types |
| 401 | unauthenticated |
| 402 | account_balance_exhausted β no credit left (top up at platform.transcribe7.com) Β· account_budget_exhausted β monthly allowance used up |
| 404 | file_not_found, transcription_not_found |
| 409 | transcription_invalid_state (e.g. transcript requested before completion) |
| 413 | file_too_large (max 1 GB), max_duration_reached (WebSocket) |
| 429 | limit_exceeded β request rate, concurrent streams or pending transcriptions (see Retry-After) |
| 503 | service_unavailable β retry shortly |
Limits are per account: concurrent real-time streams, pending transcriptions, stored files (200 / 20 GB), optional monthly audio allowance.
Usage is paid from prepaid credit: a stream or transcription needs credit to start, and a real-time stream ends with
account_balance_exhausted when the credit it may use runs out (running streams share your balance; each open file transcription holds 1 hour of credit until its real length is known).
Real-time WebSocket API
WSwss://api.transcribe7.com/transcribe-websocket
Send the key with the connection β in the Authorization: Bearer header (servers) or, in browsers, in the protocols list:
new WebSocket(url, ["t7-api-key", temporaryKey]). (An api_key field in the start message is also accepted.)
A wrong key doesn't fail the handshake: an error message arrives, then the connection closes.
- Send the start message (JSON text).
- Stream audio as binary messages, in real time (e.g. 100 ms chunks).
- Optional control messages:
{"type":"finalize"}(finalize pending tokens now),{"type":"keepalive"}(during pauses, at least every 20 s). - End of audio: send an empty binary message. Remaining tokens arrive, then
{"finished":true}, and the server closes the connection.
// Node.js (npm i ws)
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}` },
});
ws.on("open", () => {
ws.send(JSON.stringify({
model: "stt-rt-v6",
audio_format: "pcm_s16le", sample_rate: 16000, num_channels: 1,
language_hints: ["sl", "en"],
enable_speaker_diarization: true,
enable_language_identification: true,
}));
const pcm = fs.readFileSync("audio.raw"); // 16 kHz mono s16le
let i = 0;
const t = setInterval(() => {
if (i >= pcm.length) { clearInterval(t); 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) return console.error(res.error_type, res.error_message);
for (const t of res.tokens ?? []) if (t.is_final) process.stdout.write(t.text);
if (res.finished) console.log("\n[done]");
});
Start message
| Field | Description |
|---|---|
model | Real-time model, e.g. stt-rt-v6 β see GET /v1/models. |
audio_format | auto (aac, aiff, amr, asf, flac, mp3, ogg, wav, webm) or raw: pcm_s16le, pcm_f32le, mulaw, alaw⦠|
sample_rate, num_channels | Required for raw formats. |
language_hints | Expected languages, e.g. ["sl","en"]. language_hints_strict to rely on them more. |
enable_language_identification | Adds language to each token. |
enable_speaker_diarization | Adds speaker to each token. |
enable_endpoint_detection | Finalizes when the speaker stops and sends an <end> token. Tuning: endpoint_sensitivity, max_endpoint_delay_ms, endpoint_latency_adjustment_level. |
translation | {"type":"one_way","target_language":"en"} or {"type":"two_way","language_a":"sl","language_b":"en"} |
context | {"general":[{"key":"Domain","value":"medicine"}],"text":"β¦","terms":["Transcribe7"],"translation_terms":[{"source":"β¦","target":"β¦"}]} |
client_reference_id | Your own tracking id (max 256). |
Responses
{"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}
{"tokens":[],"finished":true}
is_final:false tokens are provisional and are re-sent until they become final; final tokens are sent once.
With translation, translated tokens have translation_status:"translation". Special tokens: <end> (endpoint), <fin> (after finalize).
Temporary keys
POST/v1/auth/temporary-api-key β call from your backend, hand the key to the client.
curl https://api.transcribe7.com/v1/auth/temporary-api-key \
-H "Authorization: Bearer $T7_API_KEY" -H "Content-Type: application/json" \
-d '{"usage_type":"transcribe_websocket","expires_in_seconds":60,"single_use":true,"max_session_duration_seconds":3600}'
β 201 {"api_key":"t7_temp_β¦","expires_at":"2026-11-13T10:01:00.000Z"}
// Browser
const ws = new WebSocket("wss://api.transcribe7.com/transcribe-websocket", ["t7-api-key", tempKey]);
ws.onopen = () => ws.send(JSON.stringify({ model: "stt-rt-v6", audio_format: "auto" }));
expires_in_seconds (1β3600) limits when new streams can be opened; single_use allows one stream;
max_session_duration_seconds caps each stream; client_reference_id is bound to the key.
Files
POST/v1/files | Multipart: file (+ optional client_reference_id). Max 1 GB. β 201 {"id","filename","size","created_at","client_reference_id"} |
GET/v1/files?limit=&cursor= | {"files":[β¦],"next_page_cursor":β¦} β newest first, limit 1β1000. |
GET/v1/files/count | {"playground":0,"public_api":N,"total":N} |
GET/v1/files/{id} | File metadata. |
DELETE/v1/files/{id} | 204 |
curl https://api.transcribe7.com/v1/files -H "Authorization: Bearer $T7_API_KEY" -F file=@meeting.m4a
Transcriptions
POST/v1/transcriptions β 201 transcription object
curl https://api.transcribe7.com/v1/transcriptions \
-H "Authorization: Bearer $T7_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"stt-async-v6","file_id":"84c32fc6-β¦","language_hints":["sl"],
"enable_speaker_diarization":true,"enable_language_identification":true,
"translation":{"type":"one_way","target_language":"en"},
"webhook_url":"https://example.com/hooks/t7","client_reference_id":"order-42"}'
Use either file_id (a file you uploaded) or audio_url (a public URL). Other fields: language_hints_strict,
context (as in real-time), webhook_auth_header_name / webhook_auth_header_value.
{"id":"548d023b-β¦","status":"queued","created_at":"β¦","model":"stt-async-v6","audio_url":null,"file_id":"84c32fc6-β¦",
"filename":"meeting.m4a","language_hints":["sl"],"enable_speaker_diarization":true,"enable_language_identification":true,
"audio_duration_ms":null,"error_type":null,"error_message":null,"webhook_url":"https://example.com/hooks/t7",
"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?limit=&cursor= | {"transcriptions":[β¦],"next_page_cursor":β¦} |
GET/v1/transcriptions/count | Counts. |
GET/v1/transcriptions/{id} | Status and details (poll every few seconds, or use a webhook). |
DELETE/v1/transcriptions/{id} | 204 (409 while still processing). |
Transcript
GET/v1/transcriptions/{id}/transcript (when completed)
{"id":"548d023b-β¦","text":"Hello everyoneβ¦",
"tokens":[{"text":"Hel","start_ms":0,"end_ms":180,"confidence":0.98,"speaker":"1","language":"en","translation_status":"original"}, β¦]}
Webhooks
With webhook_url we POST {"id":"β¦","status":"completed"} (or "error") when the transcription finishes,
with your webhook_auth_header_name: value if set (3 attempts). The URL must be publicly reachable. The delivery result is in webhook_status_code.
You can add your own query parameters to the URL.
Models
GET/v1/models β available models (real-time and async), their languages and translation support.
Usage
GET/v1/usage?month=2026-11 (default: this month, UTC)
{"month":"2026-11","realtime_seconds":5400,"async_seconds":7260,"total_seconds":12660,"monthly_cap_seconds":0,
"daily":[{"date":"2026-11-13","realtime_seconds":5400,"async_seconds":7260,"realtime_sessions":3,"transcriptions":2}]}
Data retention
Uploaded files are deleted 24 hours after upload, and transcriptions (with their transcripts) 24 hours after they finish. Download what you need within that time, or delete earlier yourself. Real-time audio and text are not stored.
Questions or higher limits: support@transcribe7.com