Models, Languages, and Voices
Choose the right SDK 0.18.0 language, ASR model, processing selector, TTS model, and voice.
Choose the processing workflow first. Then choose only the parameters that workflow exposes: language identifies the speech, an ASR model selects a recognizer, processing selectors modify batch output, and a TTS voice is not a model.
Make the choices in this order
- Choose batch for long-form or large complete recordings, fast for a complete latency-sensitive audio unit such as an agentic turn, realtime while audio is still arriving, or TTS when text is the input.
- For speech-to-text, choose the
Languagevalue that describes the audio. - For batch or fast transcription, choose a pipeline-specific ASR model when the operation requires or your integration intentionally pins one. Realtime transcription selects language, not an ASR model.
- Add batch processing selectors only when needed. For TTS, choose the model and then a runtime voice or voice references.
| Choice | What it controls | What it does not control |
|---|---|---|
| Language | Arabic, English, or Arabic-English code-switching input | The specific recognizer implementation |
| ASR model | Recognizer used by batch or fast transcription | Realtime language framing or TTS |
| Processing selector | Diarization, redaction, or ITN on a batch job | The ASR model itself |
| TTS model | Speech-synthesis engine | The voice identity |
| Voice | A listed voice ID or caller-supplied references | The TTS engine |
These tables document constants exported by JavaScript and Python SDK 0.18.0.
An exported constant does not guarantee that a model or voice is provisioned for
every key or environment. Use the configuration issued for your environment and
handle model-unavailable and empty-voice-list results.
Language values
The same Language members are exported in JavaScript and Python.
| SDK constant | Wire value | Realtime frame byte | Used by |
|---|---|---|---|
Language.Ar | ar | 0 | Batch path, fast metadata, realtime frames |
Language.En | en | 1 | Batch path, fast metadata, realtime frames |
Language.ArEn | codeswitch | 2 | Batch path, fast metadata, realtime frames |
| — (direct wire only) | auto | 255 | Batch path, fast metadata, realtime frames |
auto selects the automatic default configured for the environment, which
currently resolves to the code-switching model. It is a direct-wire value: SDK
0.18.0 exports no named constant for it, so reach it only through a direct
OpenAPI or AsyncAPI integration. Omitting the language where the operation
allows it has the same effect.
For direct HTTP operations, use the language values declared by the relevant
OpenAPI operation. Do not pass a batch or fast model enum to
RealtimeClient.startStream() / start_stream().
ASR models for batch and fast transcription
JavaScript and Python 0.18.0 use the same member names and wire strings.
| Wire value | Batch constant | Fast constant | Released SDK constraint |
|---|---|---|---|
nida_ar | BatchTranscriptionModel.NidaAr | FastTranscriptionModel.NidaAr | Arabic-labelled model |
nida_8k_ar | BatchTranscriptionModel.NidaArTelephony | — | Exported only for batch in 0.18.0 |
bayan_ar | BatchTranscriptionModel.BayanAr | FastTranscriptionModel.BayanAr | Arabic-labelled model |
bayan_cs_ar_en | BatchTranscriptionModel.BayanArEn | FastTranscriptionModel.BayanArEn | Unversioned Arabic-English alias |
bayan_cs_ar_en_v1 | BatchTranscriptionModel.BayanArEnV1 | FastTranscriptionModel.BayanArEnV1 | Fixed Arabic-English version |
bayan_cs_ar_en_v2 | BatchTranscriptionModel.BayanArEnV2 | FastTranscriptionModel.BayanArEnV2 | Fixed Arabic-English version |
fast_en | BatchTranscriptionModel.FastEn | FastTranscriptionModel.FastEn | English-labelled model |
The compatibility ASRModel enum contains all seven members, but new code
should use BatchTranscriptionModel or FastTranscriptionModel so an invalid
pipeline combination is harder to express. The SDK surface does not define a
quality or latency ordering between NidaAr and BayanAr; follow the model
configuration provided for your environment.
Defaults, aliases, and compatibility
| Case | Released 0.18.0 behavior |
|---|---|
| Batch ASR omitted | asr is optional; the request leaves model selection to the service. |
| Fast ASR | FastTranscriptionClient.transcribe() requires a model and a language; it still sends one complete audio unit. |
| Realtime ASR | startStream() / start_stream() requires a language and has no ASR-model parameter. |
| Arabic-English alias | Use the unversioned BayanArEn compatibility alias; choose BayanArEnV1 or BayanArEnV2 only when intentionally pinning that wire value. |
| Telephony constant | NidaArTelephony is intentionally absent from FastTranscriptionModel; treat that as a 0.18.0 compatibility constraint, not a permanent platform-availability statement. |
Fast transcription shares language and model selection with batch, but not its workload boundary: fast consumes a complete latency-sensitive audio unit; meetings, podcasts, archives, and other long-form recordings belong to batch.
Batch processing selectors
Selectors modify processing; they do not replace Language or the ASR model.
| Purpose | SDK constant or option | Outgoing value | Meaning |
|---|---|---|---|
| Diarization | BatchDiarization.Off | 0 | Turn off speaker segmentation |
| Diarization | BatchDiarization.On | 1 | Enable the default diarization selection |
| Diarization | BatchDiarization.D1 | d1 | Select diarization key d1 |
| Diarization | BatchDiarization.D2 | d2 | Select diarization key d2 |
| Redaction | BatchRedact.Off | 0 | Turn off redaction |
| Redaction | BatchRedact.On | 1 | Enable redaction |
| ITN | itn: boolean | true / false in SDK requests | Toggle inverse text normalization |
Omitting a selector omits that query parameter; do not present an omitted value
as a stable processing default. For direct REST, use the accepted values in the
current OpenAPI operation rather than copying SDK serialization. In Python,
BatchDiarization and BatchRedact are exported from
humain_voice.stt.batchtranscription, not the top-level humain_voice.stt
namespace.
TTS model and voice
| Choice | SDK surface | Value or rule |
|---|---|---|
| Model | TtsModel.Nebula | Wire value nebula; this is the SDK 0.18.0 default when model is omitted. |
| Listed voice | VoiceInfo with id, label, and profile | Call listVoices() / list_voices() and pass the returned profile id as voice_id. |
| Voice references | VoiceReference with audio and text | For the public route, supply one standard-base64 RIFF/WAVE reference containing non-empty mono PCM16 data and its transcript instead of voice_id. |
A synthesis request requires exactly one of voice_id or non-empty
voice_references in SDK 0.18.0; neither is a model constant. The direct wire
contract permits neither selector, in which case voice selection is
deployment/model-defined and no voice is guaranteed. Handle an empty voice list
instead of guessing an ID. The documentation examples pass a five-second
voice-list timeout in both languages; Python has no default timeout, while
JavaScript defaults voice listing to five seconds.
Socket.IO TTS for TtsModel.Nebula returns raw PCM16 little-endian, 24 kHz,
mono audio. Use getSampleRate() / get_sample_rate() when writing a container.
Voice identities and labels
The voice list contains only the seven multilingual profiles. Every item has
profile: { speaker: { gender, dialect }, languages } and a stable profile ID
such as the ID labeled mul_youssef. Send that ID as voice_id; Platform keeps
the physical variants internal and rejects their IDs when supplied directly.
For the current Arabic/English profiles, any Unicode Arabic-script letter in
text selects Arabic. Otherwise English is selected. Numbers, punctuation,
emoji, whitespace, and letters from non-Arabic scripts do not select Arabic.
Treat every label as a human-readable hint only. Render the structured
profile metadata, store the stable id, and never derive or match on label.
Next steps
Use a model in a request
Run a tested batch or realtime example with the released SDK contract.
Review SDK behavior
See exact client methods, options, response types, timeouts, and cleanup rules.
Choose a voice and write WAV
List runtime voices, synthesize PCM, and create a playable file.
Inspect direct API parameters
Use generated OpenAPI pages for accepted wire parameters and schemas.