Connect once. Each call then opens a context with a start frame that carries a context_id you choose, and the context takes the frames of WS /v1/tts/live and sends its events. Every event names its context. Audio comes back in binary frames that open with a header naming the context. A context ends with a closed event unless the socket closes first, and the others keep running. Each open context holds one of the plan's concurrent speech slots from its start frame until closed. The Multiplexing guide covers the frame header, restarts, and limits.
Headers#
authorizationBearer pxa_...RequiredAuthorization: Bearer pxa_... (recommended).
x-api-keypxa_...Alternative to the Authorization header. Ignored when Authorization is present.
Connect#
wss://api.paxalabs.com/v1/tts/multi JSON text frames carry control in, and control, billing, and timing events out, each naming its context. Binary frames carry audio out. Where a message below says connection, read context.
Client messages#
startConfigures the session. Must be the first frame; exactly one per connection.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"start"RequiredmodelstringRequiredTTS model id, for example paxa-tts-flash-v2.
voicestringRequiredVoice id, resolved as on POST /v1/tts. A designed voice serves the connection until it closes, even if it is deleted meanwhile.
format"mp3" or "opus" or "wav" or "pcm" or "mulaw" or "alaw"Audio format for the session's binary frames, as format on POST /v1/tts.
sample_rate8000 or 16000 or 22050 or 24000 or 32000 or 44100 or 48000Sample rate of pcm and wav, in Hz. Paxa TTS Flash v2 serves 8000, 16000, 22050, 24000, 32000, 44100, 48000, and Paxa TTS Flash serves 24000 only. For any other format the value may only restate that format's own rate, which is 8000 for mulaw and alaw. Fixed for the connection, like format. A rate the model doesn't serve answers unsupported_format. A request costs the same at every rate.
timestamps"word" or "sentence" or "utterance"Adds timing events to the session at 1.25x the standard rate, applied to the connection's cumulative character count.
speednumberSpeaking rate, as a multiplier on the voice's own design speed. It runs from 0.5 to 1.5, and 1 is the voice as designed. Rate changes how the audio sounds. It does not change how many characters were sent. A request costs the same at every rate. Values round to the nearest 0.05. Fixed for the connection, like model and voice.
language"auto" or "th" or "en" or "zh"Sets how codes, digits, and symbols are read. Words keep the language of their script, and a number inside Thai or Chinese text keeps that text's language. Elsewhere, "th" reads them in Thai (AB2039 with Thai letter names and digits) and "en" in English. "zh" reads codes in English, a number next to Chinese characters in Mandarin, and other digits and symbols in Thai. "auto", the default, takes the language most of the text is written in, counting English only in words of three or more letters, and Thai on a tie. Under "auto", a bare number, AB2039, or 250 ml reads as Thai, and ISO9001 or 100 USD as English. Text with no Thai, Chinese, digits, or counted English word reads as English when a two-letter word has a lowercase letter, such as Hi or I'm OK. Pin "th" or "en" to choose how a short number or code reads. A request costs the same in every language. Fixed for the connection, like model and voice. "auto" resolves on each leg's own text, and a leg that is only a number reads as Thai.
temperaturenumberSets how much the pacing, pauses, breaths, and melody of a reading vary from one request to the next. It runs from 0 to 2, and 0.5 is the default. They vary least at 0 and most at 2. Paxa TTS Flash v2 reads it. Any other model accepts only a value that rounds to 0.5, and any other answers validation. A request costs the same at every temperature. Values round to the nearest 0.1. Fixed for the connection, like model and voice.
textAppends text. The server auto-flushes on a newline, sentence-ending punctuation, or a buffered-length threshold, holding back a tag still open at the end of the buffer for up to that threshold.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"text"RequiredtextstringRequiredText appended to the synthesis buffer. A frame longer than the model's max_chars answers an in-band text_too_long error. Every Paxa TTS Flash v2 voice reads tags, as does a Paxa TTS Flash (paxa-tts-flash-v1) voice whose emotion_tags list is not empty. On those voices, tags that no words follow yet wait in the buffer, and each leg opens with the tags the previous leg ended in. A frame that would take the waiting tags and the opening tags past max_chars also answers text_too_long, as does one that would leave opening tags longer than half of max_chars. A frame whose tag the voice cannot read answers an in-band tag_invalid error and leaves the buffer as it was. Billing is cumulative per connection: the total charged equals what one POST /v1/tts call carrying the text of every charged leg would cost.
flushSynthesizes the buffered text now. A flush with nothing to speak in the buffer (empty, or tags alone) answers flushed immediately.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"flush"RequiredcancelStops the leg being spoken and discards the buffered text. Use it when the speaker interrupts. The leg in flight stays charged. The discarded buffer was never charged. A session that sends one sentence per frame pays only for the sentence it interrupted. The server answers cancelled, and the session stays open for more text.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"cancel"RequiredendFlushes any remaining text, then the server sends done and closes with code 1000.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"end"RequiredServer events#
Audio frames: Each frame opens with one byte counting the context id, 1 to 64, then the id in ASCII. The rest is raw audio in the context's format for its current leg. Frames of different contexts interleave. The frames of one context arrive in delivery order, up to that leg's flushed event.
startedThe session is configured and ready for text.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"started"RequiredconnectionstringRequiredConnection id; quote it in support requests (the x-request-id analog).
modelstringRequiredThe model serving this session.
voicestringRequiredCanonical voice id the session resolved to.
format"mp3" or "opus" or "wav" or "pcm" or "mulaw" or "alaw"RequiredThe audio format every binary frame of the session carries.
sample_rateintegerRequiredThe sample rate of the session's audio in Hz, which is the rate the start frame asked for or else the format's own. Check it before playing raw pcm.
timestamps"word" or "sentence" or "utterance"Echoed when the session requested timing.
speednumberEchoed when the session asked for a rate of its own.
language"th" or "en" or "zh"Echoed when the session pinned a language.
temperaturenumberEchoed when the session asked for a temperature of its own.
chargedBilling receipt, sent before the leg's audio or after its first audio frame. Receipts replace the x-credits-charged header.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"charged"RequiredseqintegerRequiredThe synthesis leg this receipt covers, starting at 1.
charsintegerRequiredCharacters synthesized in this leg.
creditsnumberRequiredCredits charged for this leg, exact to a hundredth. The 0.1-credit request floor applies once per connection, on the first charged leg.
total_creditsnumberRequiredTotal credits charged on this connection so far.
timingTiming spans; sent only when the session set timestamps.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"timing"RequiredseqintegerRequiredThe leg these spans belong to.
spansarray of objectsRequiredTimes are relative to the start of this leg's audio (each leg is an independent audio stream).
Show propertiesHide properties
spans[].textstringRequiredThe spoken input text this span covers. An emotion tag takes no span.
spans[].startnumberRequiredWhere the span begins in the audio, in seconds.
spans[].endnumberRequiredWhere the span ends in the audio, in seconds.
flushedThe buffer is drained; safe to end or keep sending.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"flushed"RequiredseqintegerRequiredAll audio and timing through leg seq have been sent and the buffer is empty. 0 when no leg has run yet.
cancelledA cancel frame was applied. The stopped leg keeps the charge its receipt reported; the discarded buffer was never charged. The session stays open, and the next text frame starts a new leg.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"cancelled"RequiredseqintegerRequiredThe leg that stopped. No further audio or timing arrives for it, and any already received is safe to discard. 0 when no leg was in flight and only the buffer was discarded.
errorSomething failed. A recoverable error leaves the context open. After a fatal one the context sends closed with the code listed below, and the socket itself closes on 4401 and 4403.
context_idstringThe context the error belongs to. Absent when the frame named no context. That is a frame that was not a JSON object, one whose context_id was missing or malformed, or a binary frame the socket does not take or whose header was malformed. Nothing closes on such an error.
type"error"RequiredcodestringRequiredStable machine-readable code from the error catalog. Branch on this field; the errors reference documents every code.
seqintegerThe leg the error belongs to, when it belongs to one.
retry_afterintegerSeconds to wait before re-flushing; sent with rate_limited.
doneEvery leg is delivered; the server closes with code 1000 after this event. A connection that closes without done did not finish delivering.
context_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
type"done"Requiredtotal_charsintegerRequiredCharacters synthesized on this connection.
total_creditsnumberRequiredCredits charged on this connection, exact to a hundredth.
closedThe context is closed, and no audio follows. A context ends with one closed event unless the socket closes first. The id is free for a new start once it arrives.
type"closed"Requiredcontext_idstringRequiredThe context this message belongs to. You choose it: 1 to 64 characters of letters, digits, and . _ : -, such as your own call id.
codeintegerRequiredThe context's close code, one of those listed below.
reasonstringRequiredThe same in words, for logs.
drainingThe server is restarting. Open another socket now and start every new context there. Contexts already open keep running. Move each call at its next turn boundary. A start sent here from now on answers provider_unavailable and closed. The socket closes with 1001 once its last context has closed.
type"draining"RequiredgraceintegerRequiredSeconds until the server closes the contexts still open on this socket.
Close codes#
| Code | Description |
|---|---|
| 1000 | A context reports it after done. The socket closes with it only when you close it. |
| 1001 | The server is restarting. A context reports it when it was still open after the grace the draining event named. The socket closes with it once its last context has closed. It can also close the socket while contexts are open, and those end with no closed event. Open another socket and start again there. |
| 1009 | The socket closes: a frame exceeded 64 KiB. |
| 4400 | A context reports it: a frame violated the session protocol, or the start frame failed validation. It also reports it when the start frame named an unknown model or voice, or a format or sample rate the model does not serve. Any other frame that fails validation answers an error event, and the context stays open. |
| 4401 | The API key stopped being valid. Every open context reports it, then the socket closes with it. |
| 4402 | A context reports it: insufficient credits for a leg. |
| 4403 | The key's spending cap was reached. Every open context reports it, then the socket closes with it. |
| 4408 | A context reports it when no frame arrived for it and no audio was delivered for 300 seconds. The socket closes with it after 300 seconds with no open context and no frame. |
| 4413 | A context reports it when its frames arrived faster than they could be handled, and a speech context also when its client read a leg too slowly for the leg's time budget, which keeps that leg's charge. The socket closes with it when the client read too slowly and the outbound buffer overflowed. |
| 4429 | A context reports it: the account holds the plan's full count of concurrent speech sessions. End another context or connection, then start again. |
| 4500 | A context reports it: internal server error. |
| 4503 | A context reports it: the start frame's model is not served right now. Nothing was charged; retry once GET /health reports it served. |