Sonex Python SDK

Official Python SDK for SonexLabs.

Requirements

• Python 3.9+
• SonexLabs API key

Installation

pip install sonexlabs

Quick Start

from sonex import Sonex

client = Sonex(api_key="YOUR_API_KEY")

Keep your API key in an environment variable rather than hard-coding it in source code.

Text-to-Speech

Only text is required. voice_id, language, speed, and output_format are optional.

audio = client.speech.create(
    text="Hello from Sonex",
)

with open("output.wav", "wb") as f:
    f.write(audio)

language defaults to "auto", speed defaults to 1.0, and output_format defaults to "wav".

Supported output formats:

• wav
• mp3
• ogg

Using a Specific Voice

Get available voices first:

voices = client.voices.list()

for voice in voices:
    print(voice.id, voice.name)

Then use the returned voice ID:

audio = client.speech.create(
    text="Hello from Sonex",
    voice_id="VOICE_ID",
)

with open("output.wav", "wb") as f:
    f.write(audio)

Streaming

Stream audio as it is generated:

with open("output.wav", "wb") as f:
    for chunk in client.speech.stream(
        text="Hello from Sonex",
    ):
        f.write(chunk)

Streaming audio is always returned as chunked WAV. output_format is not accepted for streaming.

Voices

List Voices

voices = client.voices.list()

for voice in voices:
    print(voice.id, voice.name)

Get a Voice

voice = client.voices.get("VOICE_ID")

print(voice.name)
print(voice.language)

Clone a Voice

Clone from a local audio file:

voice = client.voices.clone(
    name="My Custom Voice",
    file="reference.wav",
)

print(voice.id)

Or provide a hosted audio URL:

voice = client.voices.clone(
    name="My Custom Voice",
    audio_url="https://example.com/reference.wav",
)

print(voice.id)

Provide exactly one of file or audio_url.

The reference audio should contain at least 10 seconds of clean audio with one speaker.

Delete a Voice

client.voices.delete("VOICE_ID")

Billing

Check the current account balance:

balance = client.billing.balance()

print(balance.wallet.balance)
print(balance.wallet.currency)

for credit in balance.credits:
    print(credit.service, credit.available)

Error Handling

The SDK provides specific exceptions for common API errors:

from sonex import Sonex
from sonex.exceptions import (
    AuthenticationError,
    InsufficientBalanceError,
    RateLimitError,
    ValidationError,
)

client = Sonex(api_key="YOUR_API_KEY")

try:
    audio = client.speech.create(
        text="Hello from Sonex",
    )
except AuthenticationError:
    print("Invalid API key")
except InsufficientBalanceError:
    print("Insufficient balance")
except RateLimitError:
    print("Rate limit exceeded")
except ValidationError:
    print("Invalid request")

Context Manager

The client can be used as a context manager:

from sonex import Sonex

with Sonex(api_key="YOUR_API_KEY") as client:
    audio = client.speech.create(
        text="Hello from Sonex",
    )

    with open("output.wav", "wb") as f:
        f.write(audio)

Development

Install the package in editable mode:

python -m pip install -e .

Install the test dependency:

python -m pip install pytest

Run the test suite:

python -m pytest

Build the package:

python -m build

The distribution files are generated in the dist/ directory.

API Documentation

For the complete SonexLabs API documentation, see:

• SonexLabs Quickstart
• SonexLabs API Reference

License

Proprietary - SonexLabs.