API Guides

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/.

RouteRequest bodyResponseUse it for
sttmultipart/form-data with one fileNDJSON transcription recordsOne short, complete clip, such as a finished user turn
stt-streamOne framed PCM chunk (application/octet-stream)NDJSON transcription recordsLive transcription while audio is still arriving
diarization-streamOne framed PCM chunkNDJSON speaker-segment recordsA live speaker timeline, without text
ttsJSONFramed 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.

ParameterRequiredValue
idYesA fresh UUID per request, echoed in each record. Reusing it doesn't deduplicate.
languageNoen, ar, codeswitch, or auto. Omitted or auto uses the environment default.
langNoAlias for language, read when language is missing or empty.
asrNoAn ASR model key. Omitted, the service uses the default for the language.
modelNoAlias 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.

HTTP streaming frame
FieldBytesValue / meaning
UUID0–15Same nonzero UUID for every frame of one stream.
Flags16Bit 0 start, bit 1 final; other bits 0.
Language170 ar, 1 en, 2 codeswitch, 255 auto. Diarization accepts any of these values and ignores it.
PCM18–endPCM16 little-endian, 16 kHz, mono; even, non-zero length, no WAV header.
FrameFlags byte
First1
Middle0
Last2
Only frame3

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.

http-realtime-frame.ts
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.bin

Use 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; the stt-stream contract 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.bin

Each 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 empty 200 or 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_EXCEEDED throttle, 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.

http-diarization-stream.ts
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 26

recording.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.bin

Without 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:

HTTP TTS service frame
FieldBytesValue / meaning
UUID0–15The request id.
Final161 on the last frame; otherwise 0.
PCM17–endPCM16 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.

StatusOn these routes
400Bad id, selector, frame header or PCM, a diarization stream without a start frame, or bad TTS input.
408SESSION_IDLE_TIMEOUT: the stream went idle. Start a new UUID.
409SESSION_EXPIRED: the UUID was never started, already ended, or started twice.
413Body over the route's byte limit.
422Decoded audio, session audio, or TTS text over its limit.
500Inference failed (ASR_TRANSCRIPTION_FAILED, DIARIZATION_FAILED, TTS_SYNTHESIS_FAILED).
429SESSION_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.
503A dependency such as billing or TTS moderation couldn't decide; retryable.
504TTS_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.

Next steps

On this page