PlayHT Python Library

0.1.14 verified Fri May 01 auth: no python

The official Python client for PlayHT's text-to-speech API. Current version 0.1.14, supports Python 3.8+. The library provides async and sync clients, WebSocket streaming, and support for PlayHT 2.0 and HD voices. Release cadence is irregular.

pip install pyht

Common errors

error pyht.exceptions.NotAuthenticatedError: Authentication failed ↓

cause Missing or invalid API key or user ID.

fix

Set PLAYHT_USER_ID and PLAYHT_API_KEY environment variables, or pass them to Client().

error ModuleNotFoundError: No module named 'pyht' ↓

cause The library is not installed or the wrong Python environment is used.

fix

Run 'pip install pyht' in the correct virtual environment.

error AttributeError: module 'pyht' has no attribute 'Client' ↓

cause Older version of pyht that used a different import path.

fix

Upgrade to the latest version: pip install --upgrade pyht

error TypeError: 'TTSOptions' object is not callable ↓

cause Using TTSOptions() incorrectly, e.g., calling it instead of passing options to client.tts().

fix

Call client.tts(text=..., options=options) not client.tts(text=..., options=options()).

Warnings

breaking The API key and user ID must be provided via environment variables PLAYHT_API_KEY and PLAYHT_USER_ID, or passed directly. The library does not read .env files automatically. ↓

fix Set the environment variables or pass them explicitly.

deprecated The 'voice' parameter in TTSOptions accepts a URI string. The old pattern of using a voice name directly is no longer supported. ↓

fix Use the full S3 URI from the PlayHT dashboard.

gotcha The client.tts() returns a generator. You must iterate over it to actually process the audio. Calling it without consuming the generator may lead to silent failures. ↓

fix Use the context manager or explicitly iterate.

gotcha WebSocket connections may drop if the token expires. There is no built-in reconnection logic. ↓

fix Implement custom retry logic or re-create the client periodically.

deprecated The 'async' variant (AsyncClient) is not yet stable and may have breaking changes. ↓

fix Stick with synchronous Client for production.

Imports

Client
wrong
```
from pyht.client import Client
```
correct
```
from pyht import Client
```
The top-level import is the correct one; the internal module path may break in future versions.
TTSOptions
wrong
```
from pyht.options import TTSOptions
```
correct
```
from pyht import TTSOptions
```
TTSOptions is re-exported from the top-level module. Importing from submodules is fragile.

Format

wrong

from pyht.format import Format

correct

from pyht import Format

Format enum is available at top level.

Quickstart

Initialize a client, create TTS options, and stream audio to a file.

import os
from pyht import Client, TTSOptions, Format

client = Client(
    user_id=os.environ.get('PLAYHT_USER_ID', ''),
    api_key=os.environ.get('PLAYHT_API_KEY', ''),
)
options = TTSOptions(
    voice='s3://voice-cloning-zero-shot/xxxxx',
    format=Format.FORMAT_MP3,
    sample_rate=24000,
)
with client.tts(text="Hello, world!", options=options) as audio_stream:
    with open('output.mp3', 'wb') as f:
        for chunk in audio_stream:
            f.write(chunk)