Skip to content

Add sync/async Text-to-Speech (TTS) client - #211

Open
GISWLH wants to merge 1 commit into
xai-org:mainfrom
GISWLH:feat/tts-client
Open

GISWLH wants to merge 1 commit into
xai-org:mainfrom
GISWLH:feat/tts-client

Conversation

@GISWLH

@GISWLH GISWLH commented Sep 12, 2026

Copy link
Copy Markdown

Summary

Adds a first-class TTS client for the public documented Voice/TTS REST APIs, addressing #126.

  • client.tts.synthesize(...)POST /v1/tts (sync + async)
  • client.tts.list_voices() / client.tts.get_voice(voice_id)GET /v1/tts/voices[/{id}]
  • Typed models (TtsResponse, Voice, AudioTimestamps, OutputFormat, …)
  • Client-side validation aligned with public docs (text length, speed, codecs, replace map)
  • Handles raw audio bytes and with_timestamps JSON envelopes (supports both [start, end] and {start, end} graph_times shapes)
  • Unit tests with mocked HTTP (no live API key): success, 400/401/404/429, list/get voices, validation
  • Examples under examples/sync/tts.py and examples/aio/tts.py

API surface

from xai_sdk import Client

client = Client()
voices = client.tts.list_voices()
audio = client.tts.synthesize("Hello!", language="en", voice_id="eve")
audio.write_to_file("hello.mp3")

timed = client.tts.synthesize("Hello!", language="en", with_timestamps=True)
# timed.audio, timed.duration, timed.audio_timestamps

Deferred (intentionally out of scope for this PR)

  • WebSocket streaming TTS (wss://api.x.ai/v1/tts)
  • Custom voices CRUD (/v1/custom-voices)
  • Realtime / Speech-to-Speech

Happy to iterate if maintainers prefer different method names or want streaming in a follow-up.

Test plan

  • uv run ruff format --check / uv run ruff check on changed files
  • uv run pyright on TTS modules + clients
  • uv run pytest tests/tts_test.py tests/sync/tts_test.py tests/aio/tts_test.py -v (35 passed)
  • uv run pytest tests/sync/client_test.py tests/aio/client_test.py tests/tts_test.py tests/sync/tts_test.py tests/aio/tts_test.py -q (62 passed)

Fixes #126

Introduce first-class client.tts support for the public REST Voice/TTS APIs:
POST /v1/tts (synthesize) and GET /v1/tts/voices (list_voices / get_voice).

Includes typed models, client-side validation, raw audio vs with_timestamps
JSON envelope handling, mocked unit tests, and sync/async examples.

Fixes xai-org#126
@GISWLH
GISWLH requested a review from a team as a code owner September 12, 2026 08:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FEATURE] Support for TTS and voice api

1 participant