API GuidesSocket.IO Event Reference

Text-to-Speech

Stream PCM16 24 kHz audio over socket.io.

Text-to-Speech (TTS) over Socket.IO.

This API accepts a JSON tts request and streams binary audio chunks via tts_audio.

Quickstart

  1. Connect with the API_URL and API_KEY provisioned for the environment; API_PATH is optional and defaults to /socket.io.
  2. Request tts_voice_list; an empty array is a valid result and must not be replaced with a guessed ID.
  3. Emit tts with a fresh UUID, text containing at least one Unicode letter or number after trimming, and explicit model: "nebula".
  4. Choose either one returned voice_id or one voice_references item; do not send both.
  5. Listen for tts_audio, append bytes 17..end from every matching frame, including the final frame, and finish when byte 16 bit 0 is set.

Supported Features

  • Streaming synthesis: tts → tts_audio (binary chunks)
  • Voice profile discovery: tts_voice_list → tts_voice_list_result (seven multilingual profiles)
  • Voice adaptation: voice_references (base64 audio + transcript)
  • Emotion and speaking style: tags in text and generation_config.emotion

Emotion and speaking style

Tags in text choose how each part is spoken: in one of 7 emotions or 5 speaking styles. In the voice list, profile.emotions (neutral first) and profile.styles show what each voice supports.

Recipes: Emotion and speaking style, Voice a support agent, Narrate a story, Let an LLM write tagged text.

Deliveries

KindTags
Emotions[neutral] [happy] [sad] [angry] [fearful] [surprised] [whisper] · neutral is the default
Styles[news] [storytelling] [advertising] [call_center] [conversational]

Markup

MarkupEffect
[sad]Switches to sad from here on.
<emotion value="sad"/>, <style value="news"/>Same as [sad] and [news].
<emotion value="sad">…</emotion>, <style value="news">…</style>Applies to the wrapped text, then the outer delivery resumes. Spans can nest; close each with the name that opened it.
"generation_config": { "emotion": "news" }Sets the starting delivery for the request; tags switch from it.
news, then happy for one sentence, then news again
[news] Markets closed higher today. <emotion value="happy">A record day!</emotion> More after the break.

Rules

  • Each part of the text has one delivery: an emotion or a style, never both.
  • The last tag wins: [sad][happy] speaks happy.
  • Names are case-insensitive, and only the 12 above work. There are no aliases: [Happy] works, [joyful] doesn't.
  • An unknown name in brackets isn't a tag, so [laughter] is spoken. An unknown name in value or generation_config.emotion is ignored.
  • A delivery the voice doesn't list is skipped: the tag is removed and the current delivery continues.
  • Tags aren't spoken or billed, and don't count toward the character limit.

Limitations

  • With voice_references, tags are skipped: a cloned voice speaks in its own delivery.
  • Works in Arabic and English. Tag names stay in English in both.

Errors

Non-retryable: change the request first.

CodeCauseWhat to do
TTS_EMOTION_MARKUP_INVALIDA malformed <emotion …> tag, an unclosed span, or a close that doesn't match. message gives the offset in code points.Fix the tag at that offset.

A malformed <style tag or a stray </style> isn't an error: it's spoken as text.

Deployments that set segment limits also emit TTS_EMOTION_SEGMENT_COUNT_EXCEEDED (too many parts) and TTS_EMOTION_SEGMENT_TOO_SHORT (a part under the minimum length), both with data.

Input Validation

After trimming, top-level request text must contain at least one Unicode letter or number. Whitespace-only input emits non-retryable VALIDATION_REQUIRED_FIELD; punctuation-only input (for example -, ... or ؟) emits non-retryable VALIDATION_INVALID_PARAM. Both arrive as an error event carrying the request id. The service counts Unicode code points, not UTF-8 bytes or displayed grapheme clusters. Leading and trailing whitespace is preserved and counts toward the limit.

Inclusive defaults are 500 code points for free accounts and 1,000 for standard and enterprise accounts. Missing or unknown tiers use 500. Deployments can independently override the limits with TTS_MAX_INPUT_CHARACTERS_FREE, TTS_MAX_INPUT_CHARACTERS_STANDARD, and TTS_MAX_INPUT_CHARACTERS_ENTERPRISE; consequently the schema does not declare a fixed maxLength.

Text over the effective limit emits a non-retryable CHARACTER_COUNT_EXCEEDED error carrying data with bound tts_input_characters and unit characters. Validation happens before synthesis and before the per-key rate-limit bucket is charged.

text is plain UTF-8 text, not SSML. Delivery tags such as [happy] are removed and do not count toward the limit; see Emotion and speaking style. Any other markup carries no meaning: it counts toward the limit like any other characters, and a tag's name may be spoken.

Content policy

When content-policy enforcement is enabled, rejected text emits non-retryable TTS_INPUT_NOT_ALLOWED; change the text before trying again. If the content-moderation authority cannot make a decision, synthesis fails closed with retryable TTS_MODERATION_UNAVAILABLE. These outcomes are kept distinct so an infrastructure failure is never reported as prohibited content. Both are emitted before synthesis begins.

Voice-reference limits

voice_references accepts exactly one entry and every bound on it is checked before the model lookup, the concurrency lease and the rate-limit charge, so a rejected request consumes no quota and no slot:

  • more than one entry emits non-retryable VOICE_REFERENCE_COUNT_EXCEEDED (bound tts_voice_reference_count);
  • an explicit empty array emits non-retryable VALIDATION_INVALID_PARAM - omit the field, or send null, to use voice_id or the default voice;
  • supplying voice_id together with voice_references emits non-retryable VALIDATION_INVALID_PARAM;
  • a missing or whitespace-only reference transcript emits VALIDATION_REQUIRED_FIELD, and one with no Unicode letter or number emits VALIDATION_INVALID_PARAM;
  • a reference transcript over its own limit (default 500 code points, independent of the text budget, which it does not consume) emits CHARACTER_COUNT_EXCEEDED with bound tts_voice_reference_text_characters;
  • decoded reference audio over the byte ceiling (default 2 MiB) emits PAYLOAD_TOO_LARGE with bound tts_voice_reference_bytes, checked from the base64 length before the payload is decoded;
  • decoded reference audio longer than the duration ceiling (default 15 seconds, matching the deployed model's own reference limit, computed from the file's own declared sample rate) emits AUDIO_DURATION_EXCEEDED with bound tts_voice_reference_duration;
  • base64 that is not strictly canonical standard base64 (line breaks, spaces, the URL-safe alphabet and non-zero padding bits are all rejected), or audio that is not mono PCM16 RIFF/WAVE with non-empty data, emits VALIDATION_INVALID_FORMAT.

The byte and duration ceilings are inclusive. Deployments may lower the reference ceilings with TTS_MAX_VOICE_REFERENCE_DECODED_BYTES, TTS_MAX_VOICE_REFERENCE_DURATION_SEC and TTS_MAX_VOICE_REFERENCE_TEXT_CHARACTERS but can never raise them above the published defaults.

Lifecycle and cancellation

The Socket.IO connection owns its active synthesis RPCs; clients do not send an owner field. Disconnecting cancels only that connection's requests and suppresses later audio/error emits without closing inference connections shared with other requests. Synthesis has a non-resetting 25-second overall deadline and a 60-second inactivity watchdog. If the overall deadline wins before the final frame, the server emits retryable TTS_DEADLINE_EXCEEDED; audio already sent remains partial and must be discarded or handled as incomplete.

Credit and billing errors

Each tts request reserves credit under its id before synthesis. A refusal is an error event carrying the request id; the connection stays open.

  • CREDITS_EXHAUSTED — the account is out of credit; retryable: false.
  • BILLING_AUTHORIZATION_UNAVAILABLE — the billing authority could not reach a decision, so synthesis failed closed; retryable: true.
  • BILLING_IDEMPOTENCY_CONFLICT — the id was already used for a tts request with a different character count; retryable: false. Resending the same id fails the same way: send a new UUID for every request.

TTS Audio Output Format

Audio bytes in tts_audio (bytes 17..end) are always:

  • PCM16 little endian
  • 24 kHz
  • mono
  • raw waveform (no WAV header)

Voice Selection

voice_id (if used) is a UUID returned by tts_voice_list_result. If neither voice selector is sent, selection is deployment/model-defined and no voice is guaranteed. Released SDK 0.18.0 applies stricter client-side validation and requires exactly one selector.

The voice list contains only the seven configured multilingual profiles. Every item carries profile metadata with one speaker context and an open-ended list of supported language tags. Physical variant IDs are internal and are rejected when supplied as voice_id.

For the current Arabic/English profiles, the Arabic variant is selected when text contains any Unicode Arabic-script letter. Otherwise the English variant is selected. Numbers, punctuation, emoji, whitespace, and letters from non-Arabic scripts do not select Arabic.

A supplied voice_id is resolved before any quota deduction, rate-limit charge or inference, and its failures are typed (SAU-2258): a voice_id that is not a valid UUID emits non-retryable VALIDATION_INVALID_UUID; a well-formed voice_id that does not identify an available voice emits non-retryable TTS_VOICE_NOT_FOUND; a resolved voice whose stored data is incomplete or corrupt emits non-retryable TTS_VOICE_RESOLUTION_FAILED; and a positively classified transient database/storage outage during resolution emits retryable SERVER_DEPENDENCY_FAILURE. Because resolution precedes any charge, retrying the retryable case is safe.

Connection

Host: wss://api.voice.humain.com

Use the API_URL and API_KEY provisioned for the target environment. API_PATH is optional and defaults to /socket.io, the single path that serves every subsystem; set it only to override for a self-hosted or proxied deployment. This is Socket.IO over WebSocket, not raw WebSocket. Transport: WebSocket only — set transports: ["websocket"]. Polling is not supported.

Example (JavaScript):

const socket = io(process.env.API_URL, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: { "x-api-key": process.env.API_KEY, "Origin": process.env.API_URL }
});

Example (Python — python-socketio):

async def main() -> None:
    await sio.connect(
        os.environ["API_URL"],
        headers={"x-api-key": os.environ["API_KEY"], "Origin": os.environ["API_URL"]},
        socketio_path=os.environ.get("API_PATH", "/socket.io"),
        transports=["websocket"],
    )

asyncio.run(main())

Authentication: x-api-key (header httpApiKey).

Events

EventDirectionDescription
ttsClient → ServerClient sends JSON TTS request.
tts_audioServer → ClientServer streams TTS audio as binary chunks.
tts_voice_listClient → ServerClient requests available TTS voices.
tts_voice_list_resultServer → ClientServer returns available TTS voices.
errorServer → ClientServer emits error messages.

Messages

TTS request

tts · Client → Server

Content type: application/json

FieldTypeRequiredDescription
idstring (uuid)YesFresh UUID for this request, echoed in tts_audio frames and error events; see Credit and billing errors.
textstringYesText to speak, by default up to 500 code points for free accounts and 1,000 for standard and enterprise accounts; see Input validation. Tags such as [happy] set the delivery.
modelstringNoModel key; send nebula. If omitted, the deployment's configured default applies, falling back to nebula.
voice_idstring (uuid)NoVoice profile id from the voice list. Send it or voice_references, not both; see Voice selection.
voice_referencesTTSVoiceReference[] | nullNoOne reference clip and its transcript, to clone a voice instead of using voice_id. Omit it or send null when unused; see Voice-reference limits.
generation_configTTSGenerationConfigNoGeneration settings for the whole request.

TTSVoiceReference

FieldTypeRequiredDescription
audiostringYesBase64 mono PCM16 WAV clip of the voice, by default up to 15 seconds and 2 MiB decoded; see Voice-reference limits.
textstringYesTranscript of the reference clip, by default up to 500 code points and separate from the text limit; see Voice-reference limits.

TTSGenerationConfig

FieldTypeRequiredDescription
emotionstringNoStarting emotion or speaking style, default neutral; tags in text switch from it.

Examples

Basic TTS request

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "text": "Hello from HUMAIN Voice",
  "model": "nebula"
}

TTS request with a specific voice profile

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "text": "Hello from HUMAIN Voice",
  "model": "nebula",
  "voice_id": "19965876-8cd6-4b8c-9af4-35cbec69ff1d"
}

TTS request using voice references

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "text": "Hello",
  "model": "nebula",
  "voice_references": [
    {
      "audio": "UklGRiYAAABXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YQIAAAAAAA==",
      "text": "Reference text"
    }
  ]
}

TTS request with a starting style and an emotion tag

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "text": "Thank you for calling. [happy] Your refund is on its way!",
  "model": "nebula",
  "voice_id": "19965876-8cd6-4b8c-9af4-35cbec69ff1d",
  "generation_config": {
    "emotion": "call_center"
  }
}

TTS audio stream

tts_audio · Server → Client

Raw binary audio stream chunks for TTS.

Content type: application/octet-stream

Raw unencoded binary buffer sent as a Socket.IO binary event (tts_audio).

Client should:

  1. Read request id from bytes 0..15.
  2. Check end_of_stream in byte 16 (bit 0).
  3. Append bytes 17..end to an output buffer until end_of_stream=1.

Audio bytes format (bytes 17..end):

  • PCM16 little endian @ 24 kHz, mono (raw waveform; no WAV header).

Byte layout (offsets in bytes):

  • 0..15: id (UUID, 16 bytes)
  • 16: header (uint8)
    • bit 0: end_of_stream (final chunk)
    • bits 1-7: reserved (0)
  • 17..end: audio bytes

Example packet strings are illustrative notation. Spaces and <audio-bytes> are not transmitted.

Examples

Non-final audio chunk

12ab34cd56ef789012ab34cd56ef7890 00 <audio-bytes>

Final audio chunk

12ab34cd56ef789012ab34cd56ef7890 01 <audio-bytes>

TTS voice list request

tts_voice_list · Client → Server

Content type: application/json

FieldTypeRequiredDescription

Examples

Request all available voices

{}

TTS voice list result

tts_voice_list_result · Server → Client

Content type: application/json

Type: TTSVoiceListResult

List of available TTS voices. profile.emotions and profile.styles are described in Emotion and speaking style.

Examples

List of available voice profiles

[
  {
    "id": "af52a907-1086-46f7-8f5d-72317875d7bd",
    "label": "mul_youssef",
    "profile": {
      "speaker": {
        "gender": "male",
        "dialect": "arz"
      },
      "languages": [
        "ar",
        "en"
      ],
      "emotions": [
        "neutral",
        "happy",
        "sad",
        "angry",
        "fearful",
        "surprised",
        "whisper"
      ],
      "styles": [
        "news",
        "storytelling",
        "advertising",
        "call_center",
        "conversational"
      ]
    }
  }
]

No voices returned

[]

Error message

error · Server → Client

Content type: application/json

FieldTypeRequiredDescription
idstring (uuid)NoTTS request UUID (present when parseable from the payload)
codestringYesMachine-readable error code
messagestringYesHuman-readable error text
retryablebooleanYesWhether the client should retry
timestampstring (date-time)YesUTC RFC 3339 timestamp created when the error is emitted.
retry_after_secondsintegerNoSeconds to wait before retrying. Present only on a retryable limit rejection. This transport has no Retry-After header, so the hint travels in the frame.
dataobjectNoPresent only on limit rejections. Names the bound that was exceeded, its configured value and the observed value.

Examples

Invalid JSON payload

{
  "code": "VALIDATION_INVALID_FORMAT",
  "message": "invalid json body provided",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

The account already has as many concurrent TTS syntheses in flight as its plan allows, counted across every server instance. The limit is per BILLABLE ACCOUNT, so several API keys belonging to one account share one allowance. Retryable: it usually clears within seconds. The connection is NOT closed - other operations already admitted on this socket keep running.

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "CONCURRENCY_LIMIT_EXCEEDED",
  "message": "too many concurrent operations for this account",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z",
  "retry_after_seconds": 5,
  "data": {
    "limit": 4,
    "observed": 4,
    "unit": "operations",
    "bound": "account_concurrency_tts"
  }
}

Text is empty or contains only Unicode whitespace

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "VALIDATION_REQUIRED_FIELD",
  "message": "TTS input must contain non-whitespace text",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Text has no letter or number (punctuation-only)

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "VALIDATION_INVALID_PARAM",
  "message": "TTS input must contain at least one letter or number",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Text rejected by the TTS content policy

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "TTS_INPUT_NOT_ALLOWED",
  "message": "TTS input is not allowed",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Content-moderation authority temporarily unavailable

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "TTS_MODERATION_UNAVAILABLE",
  "message": "TTS moderation is unavailable",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

Text exceeds the default free-tier runtime limit

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "CHARACTER_COUNT_EXCEEDED",
  "message": "TTS input contains 501 characters; limit is 500",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 500,
    "observed": 501,
    "unit": "characters",
    "bound": "tts_input_characters"
  }
}

More than the published maxItems of 1

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "VOICE_REFERENCE_COUNT_EXCEEDED",
  "message": "voice_references contains 2 references; limit is 1",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 1,
    "observed": 2,
    "unit": "references",
    "bound": "tts_voice_reference_count"
  }
}

voice_id and voice_references were both supplied

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "VALIDATION_INVALID_PARAM",
  "message": "voice_id and voice_references are mutually exclusive",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Decoded reference audio exceeds the per-reference byte ceiling

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "PAYLOAD_TOO_LARGE",
  "message": "voice_references[0].audio decodes to 3145728 bytes; limit is 2097152",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 2097152,
    "observed": 3145728,
    "unit": "bytes",
    "bound": "tts_voice_reference_bytes"
  }
}

Reference clip longer than the deployed model's reference limit

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "AUDIO_DURATION_EXCEEDED",
  "message": "voice_references[0].audio is 16 seconds long; limit is 15",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 15,
    "observed": 16,
    "unit": "seconds",
    "bound": "tts_voice_reference_duration"
  }
}

Reference transcript exceeds its own independent limit

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "CHARACTER_COUNT_EXCEEDED",
  "message": "voice_references[0].text contains 501 characters; limit is 500",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "limit": 500,
    "observed": 501,
    "unit": "characters",
    "bound": "tts_voice_reference_text_characters"
  }
}

Synthesis did not complete within the overall deadline

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "TTS_DEADLINE_EXCEEDED",
  "message": "TTS synthesis deadline exceeded",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

voice_id is present but not a valid UUID (SAU-2258)

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "VALIDATION_INVALID_UUID",
  "message": "voice_id must be a valid UUID",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

voice_id is a valid UUID but does not identify an available voice (SAU-2258)

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "TTS_VOICE_NOT_FOUND",
  "message": "voice_id does not identify an available voice",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Resolved voice has incomplete/corrupt stored data; non-retryable (SAU-2258)

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "TTS_VOICE_RESOLUTION_FAILED",
  "message": "selected voice could not be resolved",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

The request id was already used for text with a different character count

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "BILLING_IDEMPOTENCY_CONFLICT",
  "message": "request id already used for a different TTS request; send a new id",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Transient database/storage outage while resolving voice_id; retryable (SAU-2258)

{
  "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
  "code": "SERVER_DEPENDENCY_FAILURE",
  "message": "voice resolution is temporarily unavailable",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z"
}

On this page