Text-to-Speech WebSocket

GET 
wss://api.knoxstudio.ai/v1/text-to-speech/:voice_id/stream-input

WebSocket TTS for chunked text (for example an LLM stream). Prefer HTTP convert when the full text is already available. GET and POST both accept the upgrade. A plain HTTP request returns 400. Stream output_format only (no WAV). Billed per character sent.

Request

Path Parameters

Name	Type	Required	Description
voice_id	String	Yes	ElevenLabs voice ID.

Query Parameters

Name	Type	Required	Description
model_id	String	No	Default eleven_multilingual_v2.
output_format	String	No	Stream formats only: mp3_22050_32, mp3_24000_48, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192, pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_32000, pcm_44100, pcm_48000, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192.
enable_logging	Boolean	No	Default true.
apply_text_normalization	String	No	auto, on, or off.
inactivity_timeout	Integer	No	Seconds before the socket closes on idle.
sync_alignment	Boolean	No	Include alignment in audio messages.
auto_mode	Boolean	No	Automatic generation triggering.

Do not put API keys in query strings when headers are available. Browser clients may use ?authorization= / ?api_key= because native WebSocket cannot set headers. Knox also accepts xi-api-key. Credentials in JSON message bodies are stripped.

Request Headers

Name	Type	Required	Description
Authorization	String	Yes	Bearer <token> Knox API key. xi-api-key is also accepted.
Upgrade	String	Yes	Must be websocket.

Client messages

Send JSON text frames:

{
  "text": "Hello from the first chunk ",
  "try_trigger_generation": true,
  "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 }
}

Flush remaining audio by sending "text": "" (and typically try_trigger_generation: true). Close the generation with an empty flush then close the socket.

model_id and voice_settings on the first message override query defaults. Do not send xi-api-key in the payload.

Server messages

{
  "audio": "<base64>",
  "isFinal": false,
  "normalizedAlignment": {},
  "alignment": {}
}

isFinal: true marks the end of audio for the flushed text.

Example

const ws = new WebSocket(
  "wss://api.knoxstudio.ai/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM/stream-input?model_id=eleven_flash_v2_5&output_format=mp3_44100_128"
);
ws.onopen = () => {
  ws.send(JSON.stringify({ text: "Hello from Knox. ", try_trigger_generation: true }));
  ws.send(JSON.stringify({ text: "", try_trigger_generation: true }));
};

Set the Knox key via Authorization on environments that allow custom headers, or xi-api-key.

Error Responses

Validation uses HTTP 422:

{
  "detail": [
    {
      "loc": ["body", "field"],
      "msg": "…",
      "type": "value_error"
    }
  ]
}

Other errors use { "detail": "message" }.

Status	When
400	WebSocket path called without Upgrade: websocket.
401	Missing or invalid API key.
402	Insufficient credits.
403	Token is not allowed to use this model.
404	Resource not found.
422	Validation error.
429	Rate limit exceeded.
500	Internal server error.