# OuteAI Python SDK

Official Python SDK for the OuteAI text-to-speech API at `https://outeai.com`.

## Installation

From PyPI:

```bash
pip install outeai
```

From this repository:

```bash
cd outeai
pip install .
```

Build distributable artifacts:

```bash
cd outeai
python -m pip install build
python -m build
```

Install async support:

```bash
pip install "outeai[async]"
```

## Authentication

Create an API key in your OuteAI account, then pass it to the client with `Authorization: Bearer <key>`.

The SDK uses `https://outeai.com` by default, so you do not need to set a base URL unless you want to override it.

## Quick Start

```python
from outeai import OuteAI

client = OuteAI(api_key="YOUR_OUTEAI_API_KEY")

voices = client.list_voices()
voice_id = voices[0]["voice_id"]

audio = client.generate_speech(
    text="Hello from OuteAI.",
    voice_id=voice_id,
)

audio.save("hello.wav")
client.close()
```

## Streaming Audio

```python
from outeai import OuteAI

client = OuteAI(api_key="YOUR_OUTEAI_API_KEY")

with client.stream_speech(
    text="This is a streaming response from OuteAI.",
    voice_id="vc_your_voice_id",
) as stream:
    stream.save("streamed.wav")
```

You can also iterate the WAV bytes yourself:

```python
with client.stream_speech(
    text="Chunked audio output.",
    voice_id="vc_your_voice_id",
) as stream:
    for chunk in stream:
        print(f"received {len(chunk)} bytes")
```

## Voice IDs

Voice clone management is intentionally not part of this SDK surface. Pass an existing `voice_id` into the TTS methods.

## Async Usage

```python
import asyncio

from outeai import AsyncOuteAI


async def main() -> None:
    client = AsyncOuteAI(api_key="YOUR_OUTEAI_API_KEY")

    voices = await client.list_voices()
    voice_id = voices[0]["voice_id"]

    audio = await client.generate_speech(
        text="Hello from the async OuteAI client.",
        voice_id=voice_id,
    )
    audio.save("hello-async.wav")

    await client.stream_speech_to_file(
        "stream-async.wav",
        text="This file was written from the async streaming client.",
        voice_id=voice_id,
    )

    await client.close()


asyncio.run(main())
```

## Available Methods

- `client.health()`
- `client.list_voices()`
- `client.generate_speech(...)`
- `client.generate_speech_to_file(...)`
- `client.stream_speech(...)`
- `client.stream_speech_to_file(...)`
- `AsyncOuteAI.health()`
- `AsyncOuteAI.list_voices()`
- `AsyncOuteAI.generate_speech(...)`
- `AsyncOuteAI.generate_speech_to_file(...)`
- `AsyncOuteAI.stream_speech(...)`
- `AsyncOuteAI.stream_speech_to_file(...)`

## Error Handling

API errors raise `OuteAIAPIError`.

```python
from outeai import OuteAI, OuteAIAPIError

client = OuteAI(api_key="YOUR_OUTEAI_API_KEY")

try:
    client.list_voices()
except OuteAIAPIError as exc:
    print(exc.status_code)
    print(exc.code)
    print(exc.message)
```

## Notes

- TTS responses are returned as WAV audio.
- The default TTS model is `outetts_1_pro`.
- `voice_id` is required for generation and must belong to the authenticated user.
