HTTP streaming API
Call the HUMAIN Voice HTTP streaming routes directly to transcribe a clip, stream live audio for transcription or speaker diarization, and capture text-to-speech frames.
The SDKs use Socket.IO and don't call these routes. Use them from a backend that holds the API key,
and send it in x-api-key. No Origin header is needed (Authentication).
Routes
All routes take POST under $API_URL/realtime/http/.
| Route | Request body | Response | Use it for |
|---|---|---|---|
stt | multipart/form-data with one file | NDJSON transcription records | One short, complete clip, such as a finished user turn |
stt-stream | One framed PCM chunk (application/octet-stream) | NDJSON transcription records | Live transcription while audio is still arriving |
diarization-stream | One framed PCM chunk | NDJSON speaker-segment records | A live speaker timeline, without text |
tts | JSON | Framed 16 kHz PCM (application/octet-stream) | A protocol capture of synthesized speech |
For long recordings, use batch. Which workflow fits which job is in Concepts.
Selectors and precedence
Only stt takes query parameters. The streaming routes carry the language in the frame header, and
the service picks the model.
| Parameter | Required | Value |
|---|---|---|
id | Yes | A fresh UUID per request, echoed in each record. Reusing it doesn't deduplicate. |
language | No | en, ar, codeswitch, or auto. Omitted or auto uses the environment default. |
lang | No | Alias for language, read when language is missing or empty. |
asr | No | An ASR model key. Omitted, the service uses the default for the language. |
model | No | Alias for asr, read when asr is missing or empty. |
A nonempty language wins over lang, and a nonempty asr wins over model. An invalid value
in the winning parameter returns 400 even when the alias is valid. Language values and model keys
are in Models.
curl -sS -N -X POST "$API_URL/realtime/http/stt?id=$(uuidgen)&language=codeswitch&asr=bayan_cs_ar_en" \
-H "x-api-key: $API_KEY" \
-F "[email protected]"The response is NDJSON. Read records until one has is_final: true:
{"id":"8b356f13-1caa-4487-a06c-48728c46906d","seq":0,"transcription":"Yeah, I mean, look, …","words":[{"start_time":0.14,"end_time":0.38,"word":"Yeah,"}],"is_final":true}Accepted file formats and size limits are in Concepts and Limits.
Frame format
Every stt-stream and diarization-stream POST body is one frame: an 18-byte header followed by
raw PCM. It's the same layout as the Socket.IO audio_stream frame without the diarization bit.
| Field | Bytes | Value / meaning |
|---|---|---|
| UUID | 0–15 | Same nonzero UUID for every frame of one stream. |
| Flags | 16 | Bit 0 start, bit 1 final; other bits 0. |
| Language | 17 | 0 ar, 1 en, 2 codeswitch, 255 auto. Diarization accepts any of these values and ignores it. |
| PCM | 18–end | PCM16 little-endian, 16 kHz, mono; even, non-zero length, no WAV header. |
| Frame | Flags byte |
|---|---|
| First | 1 |
| Middle | 0 |
| Last | 2 |
| Only frame | 3 |
Every frame carries audio; there is no empty terminator, so set the final bit on the last real
chunk. A frame shorter than 18 bytes, with a reserved bit set, a zero UUID, an unknown language byte, or empty or
odd-length PCM returns 400. Convert a recording to recording.pcm with the ffmpeg command in
Realtime transcription.
This example frames recording.pcm as a one-frame stream and writes frame.bin. For a longer
stream, reuse STREAM_ID and set IS_START=0 or IS_FINAL=0 per chunk.
import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';
const languageBytes = {
ar: 0,
en: 1,
codeswitch: 2,
auto: 255,
} as const;
function uuidBytes(id: string): Uint8Array {
const hex = id.replaceAll('-', '');
if (!/^[0-9a-f]{32}$/i.test(hex) || /^0{32}$/.test(hex)) {
throw new Error('STREAM_ID must be a nonzero UUID');
}
return Uint8Array.from(hex.match(/.{2}/g)!, (byte) => Number.parseInt(byte, 16));
}
function frame(
id: string,
pcm16le: Uint8Array,
options: { language: keyof typeof languageBytes; isStart: boolean; isFinal: boolean },
): Uint8Array {
if (pcm16le.byteLength === 0 || pcm16le.byteLength % 2 !== 0) {
throw new Error('PCM16 payload must be nonempty and contain an even number of bytes');
}
const output = new Uint8Array(18 + pcm16le.byteLength);
output.set(uuidBytes(id), 0);
output[16] = (options.isStart ? 1 : 0) | (options.isFinal ? 2 : 0);
output[17] = languageBytes[options.language];
output.set(pcm16le, 18);
return output;
}
async function main(): Promise<void> {
const inputPath = process.argv[2] ?? 'recording.pcm';
const outputPath = process.argv[3] ?? 'frame.bin';
const streamId = process.env.STREAM_ID ?? randomUUID();
const pcm = await readFile(inputPath);
// Defaults frame a one-chunk stream; reuse STREAM_ID and set IS_START/IS_FINAL for longer ones.
const body = frame(streamId, pcm, {
language: 'codeswitch',
isStart: process.env.IS_START !== '0',
isFinal: process.env.IS_FINAL !== '0',
});
await writeFile(outputPath, body);
console.info('status:', 'framed', streamId, body.byteLength, outputPath);
}
void main().catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
Expected output (illustrative):
status: framed f2e3e25d-f091-4a96-a5ab-7c8468529d3a 2323490 frame.binUse 1 s frames for stt-stream and diarization-stream; this example builds one frame for
illustration.
Streaming transcription
Send one frame per POST to stt-stream as audio arrives, in order, reusing the stream UUID.
- Send about 1 s of audio (32,000 bytes) per POST. While a POST waits on its response, queue new audio and send everything queued as the next frame.
- Send one POST at a time per stream UUID, as the examples do. On
diarization-stream, concurrent POSTs for one UUID aren't supported; thestt-streamcontract doesn't define them. - Set a timeout on each POST (the examples use 30 s). Timing out the final response cancels the stream.
curl -sS -N -X POST "$API_URL/realtime/http/stt-stream" \
-H "x-api-key: $API_KEY" \
-H "content-type: application/octet-stream" \
--data-binary @frame.binEach 200 carries zero or more NDJSON records with id, seq, transcription, words,
is_speech_final, and is_final:
{"id":"f2e3e25d-f091-4a96-a5ab-7c8468529d3a","seq":0,"transcription":"وبالتالي بنجاح تام","words":[{"start_time":20.19,"end_time":20.67,"word":"وبالتالي"},{"start_time":20.67,"end_time":21.27,"word":"بنجاح"},{"start_time":21.27,"end_time":22.13,"word":"تام"}],"is_final":false,"is_speech_final":true}
{"id":"f2e3e25d-f091-4a96-a5ab-7c8468529d3a","seq":0,"transcription":"في الفضاء","words":[{"start_time":71.48,"end_time":71.64,"word":"في"},{"start_time":71.64,"end_time":72.55,"word":"الفضاء"}],"is_final":true,"is_speech_final":true}- Buffer the body and split on newlines; one network read can hold part of a record or several.
- A response for a non-final chunk closes after up to 2 seconds. That's normal: the session stays open, and later records arrive on later responses.
- The response to the final chunk stays open until the service sends
is_final: true. An empty200or a closed response isn't the end of the stream. - After the first audio block reaches inference, an unfinished ASR stream expires after 60 seconds without another forwarded audio block. Inference responses do not reset this timer.
- Aborting a POST cancels the stream. After a failed POST nothing resumes, so start again with a
new UUID. The exception is a
429 SESSION_BYTE_RATE_EXCEEDEDthrottle, where the session stays live.
The diarization example below uses the same send loop. For stt-stream,
change the route and handle transcription records as described in
Concepts.
Live diarization
diarization-stream takes the same frames and returns a speaker timeline. It has no query
parameters and no model selector.
Keep at most one POST in flight per stream UUID: concurrent POSTs for the same UUID can deliver records to the wrong response. Have one sender read each response to the end before it sends the next frame. Streams with different UUIDs can run in parallel.
Each record has id, final_segments, active_segments, and is_final. Add each record's
final_segments to your timeline, replace the previous active_segments, and finish on
is_final: true. A final record can still carry active segments; keep them as provisional. Labels
are stream-relative (Speaker timelines).
This example streams recording.pcm in 1 s (32,000-byte) frames, one POST at a time, using the
send loop from Streaming transcription, and writes the timeline to
recording.rttm.
import { randomUUID } from 'node:crypto';
import { readFile, writeFile } from 'node:fs/promises';
type Segment = { start_time: number; end_time: number; speaker: string };
type DiarizationRecord = {
final_segments?: Segment[];
active_segments?: Segment[];
is_final?: boolean;
};
function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
const value = process.env[name];
if (!value) throw new Error(`${name} is required`);
return value;
}
function frame(
id: string,
pcm: Uint8Array,
isStart: boolean,
isFinal: boolean,
): Uint8Array<ArrayBuffer> {
const hex = id.replaceAll('-', '').match(/.{2}/g)!;
const output = new Uint8Array(18 + pcm.byteLength);
output.set(Uint8Array.from(hex, (byte) => Number.parseInt(byte, 16)), 0);
output[16] = (isStart ? 1 : 0) | (isFinal ? 2 : 0);
output[17] = 2; // code-switch; ignored by diarization but must be valid.
output.set(pcm, 18);
return output;
}
function toRttm(segments: Segment[], uri: string): string {
return segments
.map(
(s) =>
`SPEAKER ${uri} 1 ${s.start_time.toFixed(3)} ` +
`${(s.end_time - s.start_time).toFixed(3)} <NA> <NA> ${s.speaker} <NA> <NA>\n`,
)
.join('');
}
async function main(): Promise<void> {
const inputPath = process.argv[2] ?? 'recording.pcm';
const outputPath = process.argv[3] ?? 'recording.rttm';
const url = `${requiredEnv('API_URL')}/realtime/http/diarization-stream`;
const apiKey = requiredEnv('API_KEY');
const pcm = await readFile(inputPath);
const streamId = randomUUID();
const chunkBytes = 32_000;
const finalized: Segment[] = [];
let active: Segment[] = [];
let done = false;
for (let offset = 0; offset < pcm.byteLength && !done; offset += chunkBytes) {
const chunk = pcm.subarray(offset, offset + chunkBytes);
const isFinal = offset + chunkBytes >= pcm.byteLength;
const response = await fetch(url, {
method: 'POST',
headers: { 'x-api-key': apiKey, 'content-type': 'application/octet-stream' },
body: frame(streamId, chunk, offset === 0, isFinal),
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
for (const line of (await response.text()).split('\n')) {
if (!line.trim()) continue;
const record = JSON.parse(line) as DiarizationRecord;
finalized.push(...(record.final_segments ?? []));
active = record.active_segments ?? [];
if (record.is_final) done = true;
}
}
if (!done) throw new Error('stream ended without a final record');
const timeline = [...finalized, ...active].sort((a, b) => a.start_time - b.start_time);
await writeFile(outputPath, toRttm(timeline, 'recording'), 'utf8');
console.info('status:', 'segments', timeline.length);
}
void main().catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
Expected output (illustrative):
status: segments 26recording.rttm then holds one line per segment:
SPEAKER recording 1 0.080 1.680 <NA> <NA> SPEAKER_01 <NA> <NA>
SPEAKER recording 1 1.920 5.840 <NA> <NA> SPEAKER_01 <NA> <NA>Text to speech
The JSON body takes the same fields as the Socket.IO tts event: id, text, model, and one
of voice_id or voice_references (field table).
Send model: "nebula". There is no HTTP voice list; get a voice_id from
the voice list.
curl -sS -X POST "$API_URL/realtime/http/tts" \
-H "x-api-key: $API_KEY" \
-H "content-type: application/json" \
--data '{"id":"7f51f2c2-e7bc-41c8-a850-f848df2ddfc8","text":"Hello from HUMAIN Voice","model":"nebula"}' \
--output tts-frames.binWithout voice_id or voice_references, the deployment picks the voice.
A 200 body is a run of service frames, each laid out as below, with no length field or
delimiter between them:
| Field | Bytes | Value / meaning |
|---|---|---|
| UUID | 0–15 | The request id. |
| Final | 16 | 1 on the last frame; otherwise 0. |
| PCM | 17–end | PCM16 little-endian, 16 kHz, mono. |
tts-frames.bin isn't playable as raw PCM or WAV: frame headers sit inside the audio, and HTTP
reads don't line up with frame boundaries, so you can't strip them reliably. For playable audio, use
the SDK or Socket.IO TTS,
which delivers 24 kHz frames one per event. Aborting the request cancels its synthesis.
Errors
Errors before output starts arrive as an ErrorResponse JSON body. Branch on code and
retryable.
| Status | On these routes |
|---|---|
400 | Bad id, selector, frame header or PCM, a diarization stream without a start frame, or bad TTS input. |
408 | SESSION_IDLE_TIMEOUT: the stream went idle. Start a new UUID. |
409 | SESSION_EXPIRED: the UUID was never started, already ended, or started twice. |
413 | Body over the route's byte limit. |
422 | Decoded audio, session audio, or TTS text over its limit. |
500 | Inference failed (ASR_TRANSCRIPTION_FAILED, DIARIZATION_FAILED, TTS_SYNTHESIS_FAILED). |
429 | SESSION_BYTE_RATE_EXCEEDED: wait Retry-After, then resend the same frame; the session stays live. CONCURRENCY_LIMIT_EXCEEDED / SESSION_SLOTS_EXHAUSTED: see Errors and limits. |
503 | A dependency such as billing or TTS moderation couldn't decide; retryable. |
504 | TTS_DEADLINE_EXCEEDED: synthesis passed 25 s before output started; retryable. |
A failure after output has started ends the 200 without an error JSON: NDJSON stops before
is_final: true, and a TTS body stops before its final frame. Treat that as incomplete, keep
partial results apart, and retry with a new UUID (after a 429 throttle, resend the same frame
instead). These routes have no replay or
idempotency, so don't resend a completed stt upload blindly. Codes, limits, 429 sources, and
retry rules are in Errors and limits.