API Documentation

Welcome to the OuteAI API. Our platform provides powerful generative models. This documentation will guide you through integrating our Text-to-Speech (TTS) capabilities into your applications.

To get started, you'll need an API token, which authenticates your requests. You can generate and manage your tokens from your Account page.

Authentication

All API requests must be authenticated using an API token. The token should be passed as a URL query parameter named token.

Requests made without a valid token will fail with a 401 Unauthorized error.

# Example of an authenticated request URL
https://outeai.com/api/v1/audio?token=YOUR_API_TOKEN

API Endpoints

Text-to-Speech

POST/api/v1/audio

This endpoint converts text into spoken audio. It supports various models, voices, languages, and streams the response back.

Request Body

The request body must be a JSON object containing the parameters for audio generation.

Example Request

from outeai import OuteAI, APIError

try:
    # It is recommended to set the token as an environment variable
    # Reads from OUTEAI_API_TOKEN automatically
    client = OuteAI()

    # Or initialize the client with the token directly
    # client = OuteAI(token="your_access_token_here")

    print("Generating audio...")
    output = client.generate.audio(
        model="OuteTTS-1-Pro",
        text="Hello, world! This is a test of the text to speech API.",
        speaker_id="EN-FEMALE-1-NEUTRAL",
        temperature=0.4
    )

    # The output object contains the audio data and can be saved directly
    output.save("generated_audio.mp3")

    print(f"Audio generation complete. Duration: {output.duration:.2f}s")

except APIError as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    # It's good practice to close the client
    if 'client' in locals():
        client.close()

import asyncio
from outeai import AsyncOuteAI, APIError

async def main():
    # Using the client as an async context manager handles setup and teardown
    async with AsyncOuteAI() as client:
        try:
            print("Generating audio asynchronously...")
            output = await client.generate.audio(
                model="OuteTTS-1-Pro",
                text="This is an asynchronous test of the API.",
                speaker_id="EN-FEMALE-1-NEUTRAL",
                temperature=0.5
            )

            output.save("generated_audio_async.mp3")
            print(f"Async audio generation complete. Duration: {output.duration:.2f}s")

        except APIError as e:
            print(f"An API error occurred: {e}")
        except Exception as e:
            print(f"An unexpected error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(main())

curl -X POST "https://outeai.com/api/v1/audio?token=YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "OuteTTS-1-Pro",
       "prompt": "Hello, world!",
       "speaker_type": "default",
       "speaker_id": "EN-FEMALE-1-NEUTRAL",
       "temperature": 0.4
     }' \
     --output response.ndjson

SDKs

Python SDK

We provide a convenient Python SDK, outeai, to simplify interactions with our API. We highly recommend using it for a seamless development experience.

Installation

pip install outeai

Handling Streams

The Text-to-Speech endpoint returns a streaming response with the content type application/x-ndjson (newline-delimited JSON). This allows you to receive real-time progress updates while the audio is being generated, with the complete audio file delivered in the final message of the stream.

Each line in the stream is a separate JSON object. While generation is in progress, you will receive one or more objects where audio_data is an empty string. These objects can be used to track progress via the audio_token_count field. The very last object in the stream is the only one that will contain the complete audio as a base64-encoded string in the audio_data field.

Streamed Object Structure

{
  "audio_data": "",
  "audio_token_count": 128
}
{
  "audio_data": "",
  "audio_token_count": 256
}
{
  "audio_data": "UklGRi...CwA=",
  "audio_token_count": 256
}

Error Codes

The API uses standard HTTP status codes to indicate the success or failure of a request. A JSON body with an error message may also be returned.

Default Speaker IDs

When using the "default" speaker type, you can use any of the following pre-made voices. Simply copy the desired Speaker ID and use it in your API request.