Metadata-Version: 2.4
Name: outeai
Version: 2.0.0
Summary: Official Python SDK for the OuteAI text-to-speech API.
Project-URL: Homepage, https://outeai.com
Project-URL: Documentation, https://outeai.com
Author: OuteAI
Keywords: audio,outeai,sdk,speech,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: requests<3,>=2.31.0
Provides-Extra: async
Requires-Dist: httpx<1,>=0.27.0; extra == 'async'
Description-Content-Type: text/markdown

# 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.
