SDK Overview

Use this page to choose a workload and runtime. Then move to the JavaScript or Python guide for exact constructors, options, response fields, event constants, and tested programs. The Go SDK is released from the same contract and links to its source documentation below.

Choose by task

Start with the shape of the audio, not the client name:

Fast transcription is for a bounded, complete, latency-sensitive unit. It is not the path for a long recording or podcast; use Batch for those workloads.

Subtitles shapes completed word timing after you choose a transcription client. RealtimeSubtitles is also exported, but its id:seq deduplication requires the wire to provide distinct sequence values; see the finality section below. They are result helpers, not transport clients.

If you need direct HTTP streaming instead of an SDK client, use the Realtime HTTP guide.

Choose a server runtime

Handle TTS content-policy outcomes

The JavaScript isTtsCode() / isTtsOwned(), Python is_tts_code() / is_tts_owned(), and Go IsTTSCode() / IsTTSOwned() helpers classify both codes as TTS-owned. Preserve the structured callback before the synthesis call rejects with its generic message-only error.

The JavaScript package does not publish a minimum Node.js or Bun version. The documentation fixtures run under Node.js 24 and Bun 1.3.14; those versions describe the docs verification environment, not an SDK support promise.

Use humain_voice for new Python code. The historical sautech namespace in 0.18.0 remains a compatibility import and emits a deprecation warning.

Configure release 0.18.0

Set the values issued for your environment in a trusted server runtime:

export API_URL="https://api.voice.humain.com"
export API_KEY="YOUR_API_KEY"
export API_VERSION="v1"

Batch uses API_URL, API_KEY, and API_VERSION. Socket.IO clients require only API_URL and API_KEY and default to /socket.io. Set API_PATH only when a deployment uses an override; the legacy sautech.humain.com endpoint requires /realtime/socket.io.

See Authentication for your organization's credential flow and server-side key handling.

Own lifecycle and deadlines

Close the stream and its client

A successful stream close usually releases its Socket.IO session when no request contexts remain. A routed error can remove its request context before close() runs, so the owning scope must still clean up the client.

Use finally for JavaScript clients. In Python, use the supported async or synchronous context manager where the language guide shows it. Stop sending audio after an error and disconnect even when a per-stream close has already returned.

Set a deadline for each operation

• Batch: transcribe polls every 2 seconds with a 300-second default polling-loop threshold. Submission and an in-flight request can extend wall time. The helper does not stop on cleared and instead reaches the threshold.
• Fast transcription: JavaScript has no SDK request-timeout option. Python defaults to 60 seconds. Keep an application deadline in either runtime.
• Realtime ASR: stream close waits up to 1 second for the final result by default. Expiry ends the wait; it does not prove that a final result arrived.
• Realtime diarization: close waits up to 5 seconds and returns the best-known reconciled timeline if the final-result wait expires.
• Voice list and TTS: JavaScript defaults to 5 seconds for voice listing and 30 seconds of inactivity for synthesis. Python applies no timeout unless you pass one. These are client controls; the service also enforces a non-resetting 25-second overall synthesis deadline and a 60-second inactivity watchdog. Handle an empty voice list and close the client in both runtimes.

Interpret results by stage

Distinguish provisional and terminal results

• Batch: treat done, failed, and cleared as terminal in an application-owned poller. The released transcribe helper succeeds on done, raises on failed, and does not terminate early on cleared.
• Fast transcription: use is_final to replace partial text with the final result for the complete audio unit.
• Realtime ASR: a result is provisional while both is_final and is_speech_final are false. Replace provisional UI text instead of appending it as a second transcript.
• Realtime diarization: segments is the reconciled timeline; newlyFinalized / newly_finalized is only the new final delta.
• TTS: collect or stream audio until is_last; the returned bytes are raw PCM16, not a WAV container.

Generate subtitles only from finalized timing

Batch Subtitles.fromResponse() in JavaScript and result.subtitles() in Python read normalized word offsets and render SRT or WebVTT. RealtimeSubtitles ignores partial responses and deduplicates final responses by id:seq. The current Realtime wire contract does not guarantee distinct seq values, so collect final-event words in arrival order and render them with Subtitles when a stream can produce multiple final events. The app still owns provisional on-screen text.

Speaker segments are a different output. Export them with toRttm() in JavaScript or to_rttm() in Python, or reconcile them with finalized ASR words when producing speaker-attributed captions.

Preserve structured errors before retrying

Batch HTTP exceptions expose typed status, code, retryability, capacity, and retry-delay fields using statusCode / retryAfter in JavaScript and status_code / retry_after in Python when available.

Fast transcription and TTS error callbacks can retain a structured ErrorResponse. Their rejected JavaScript promises or Python calls use generic message-only errors on the routed failure path, so record structured callback fields before cleanup.

maxRetries / max_retries is deprecated and ignored in 0.18.0. Add bounded retry policy in the application and do not blindly repeat an ambiguous upload. See Errors and Rate Limits.

Next steps

Choose one guide and follow its tested program for your selected client. The language pages are the reference for exact public methods and language-specific cleanup; this overview is the decision map.