Metadata-Version: 2.4
Name: sonexlabs
Version: 0.1.0
Summary: Official Python SDK for SonexLabs
Author: SonexLabs
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0

# Sonex Python SDK

Official Python SDK for SonexLabs.

## Requirements

* Python 3.9+
* SonexLabs API key

## Installation

```bash
pip install sonexlabs
```

## Quick Start

```python
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.

```python
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:

```python
voices = client.voices.list()

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

Then use the returned voice ID:

```python
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:

```python
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

```python
voices = client.voices.list()

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

### Get a Voice

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

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

### Clone a Voice

Clone from a local audio file:

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

print(voice.id)
```

Or provide a hosted audio URL:

```python
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

```python
client.voices.delete("VOICE_ID")
```

## Billing

Check the current account balance:

```python
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:

```python
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:

```python
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:

```bash
python -m pip install -e .
```

Install the test dependency:

```bash
python -m pip install pytest
```

Run the test suite:

```bash
python -m pytest
```

Build the package:

```bash
python -m build
```

The distribution files are generated in the `dist/` directory.

## API Documentation

For the complete SonexLabs API documentation, see:

* [SonexLabs Quickstart](https://docs.sonexlabs.com/quickstart)
* [SonexLabs API Reference](https://docs.sonexlabs.com/api-reference)

## License

Proprietary - SonexLabs.
