Download the dated JSON reference pack.
It is designed for code generation and local validation; it is not a substitute
for
GET /v1/voices, account entitlement checks, or the Omni configured
acknowledgement.Pick a product before a language
Use the language support table for accepted and
served languages by product. Omni accepts some staged languages that may fall
back; inspect
configured.language_active and language_fallback. A Speak
catalog group does not establish end-to-end Omni support.
English is a language; accent is a voice choice
Selectingen-IN does not transform an American voice into Indian English. Use
an accent-specific voice ID, then listen to the exact configuration before you
ship it.
Evaluate names, numbers, dates, phone numbers, interruptions, and short
conversational replies. Evaluate Hindi and Hinglish separately from Indian
English; a catalog identifier is not a quality result.
Copy a complete Omni configuration
This is the body of a tagged0x03 configure frame, not a REST request or a
complete browser client:
voice_instruct
for a new neutral session. Send an empty string to reset a saved custom value;
unsupported custom instructions return unsupported_voice_instruct without
applying the configure frame. Check configured.voice_instruct_supported and
any later voice_capabilities event for effective capability.
Keep wording and conversation instructions in the persona. Speak has its own
conditional emotion control; Cast exposes emotion and intensity through its
capabilities endpoint. See agent voice settings
and the product guides before applying a control.
After sending configure, require the session to confirm any capabilities your
application needs:
Conversation timing and silence
Omni has a sessionendpointing_ms control and an Agent/session idle_check_in
preset (auto, patient, off). The deprecated barge_sensitivity and
ack_mode Agent fields are stored for compatibility and do not tune the runtime.
Do not map a responsiveness slider to an invented scale or present a saved value
as evidence of application. See the controls contract and effective
acknowledgement
and machine-readable matrix.
Delivery is an observed behavior
Speak
stream: true means the request accepts streamed delivery. If the server
returns x-pyai-stream: buffered, it completed successfully but audio was
buffered before delivery. Record that mode when measuring time to first audible
audio.
Launch check
- Query
GET /v1/voicesand retain the canonical ID, aliases,available_on, and delivery metadata you selected. - Mint a short-lived, origin-bound browser session token on your backend; do not expose a PyAI API key in the browser.
- Configure Omni, wait for
configured, and compare requested versus served language, voice, and tier. - Start microphone capture and playback only after required configuration is
active. On
flush, stop local playback and clear queued audio immediately. - Test microphone denial, cancellation while connecting, duplicate start/stop, language fallback, failed configuration, interruptions, tool timeout, and duplicate tool delivery.
call_id, and callback-delivery identity separately. Authorize the
customer tenant in the customer backend and return a durable prior result when
the same invocation is delivered again. See Omni tools.
Language support
Accepted, served, and fallback language behavior.
Omni protocol
Tagged frames and the configured acknowledgement.
Browser voice agent
A complete microphone-to-playback client.
Speak
Voice catalog, delivery modes, and audio formats.