Xai.Realtime (xai v0.1.0)

Copy Markdown View Source

WebSocket client for xAI realtime voice and streaming TTS.

xAI exposes realtime features over WebSocket (not gRPC):

  • wss://api.x.ai/v1/realtime for full voice agents (bidirectional audio + text)
  • wss://api.x.ai/v1/tts for bidirectional streaming TTS

This module uses Websockex. It is separate from the gRPC Xai.Client because the transports are different.

Example: Streaming TTS

{:ok, pid} = Xai.Realtime.connect_tts(
  api_key: System.get_env("XAI_API_KEY"),
  voice: "eve",
  codec: "mp3",
  on_audio: fn audio_chunk -> play_audio(audio_chunk) end
)

Xai.Realtime.send_text(pid, "Hello from Elixir. ")
Xai.Realtime.send_text(pid, "This is streaming TTS.")
Xai.Realtime.send_text_done(pid)

For full realtime voice agents, use connect_realtime/1 and handle events.

Summary

Types

on_audio()
on_event()
t()

Functions

close(pid)

Close the connection gracefully.

connect_realtime(opts \\ [])

Connect to the full realtime voice agent endpoint.

connect_tts(opts \\ [])

Connect for streaming TTS (text → audio chunks).

send_event(pid, event)

Send raw event (for advanced realtime use).

send_text(pid, text)

Send a text delta for TTS or conversation.

send_text_done(pid)

Signal end of text for current utterance (TTS).

text_clear()

Builds a text.clear event for barge-in.

text_delta(delta)

Builds a text.delta event. Useful for testing and for users who want raw events.

text_done()

Builds a text.done event.

Types

on_audio()

@type on_audio() :: (binary() -> any())

on_event()

@type on_event() :: (map() -> any())

t()

@type t() :: pid()

Functions

close(pid)

Close the connection gracefully.

connect_realtime(opts \\ [])

@spec connect_realtime(keyword()) :: {:ok, t()} | {:error, term()}

Connect to the full realtime voice agent endpoint.

Similar options, plus session configuration sent after connect.

connect_tts(opts \\ [])

@spec connect_tts(keyword()) :: {:ok, t()} | {:error, term()}

Connect for streaming TTS (text → audio chunks).

Options:

  • :api_key (required, or XAI_API_KEY env)
  • :voice - default "eve"
  • :language - default "en"
  • :codec - mp3, wav, pcm, etc.
  • :sample_rate
  • :on_audio - callback for base64-decoded audio chunks
  • :on_event - callback for all JSON events (optional)

send_event(pid, event)

Send raw event (for advanced realtime use).

send_text(pid, text)

Send a text delta for TTS or conversation.

send_text_done(pid)

Signal end of text for current utterance (TTS).

text_clear()

Builds a text.clear event for barge-in.

text_delta(delta)

@spec text_delta(String.t()) :: map()

Builds a text.delta event. Useful for testing and for users who want raw events.

text_done()

Builds a text.done event.