> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audixa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Audixa Text-to-Speech API

Welcome to the Audixa API Reference. This section provides detailed documentation for all API endpoints.

## Base URL

All API requests are made to:

```
https://api.audixa.ai/v3
```

## Authentication

All endpoints require authentication via the `x-api-key` header:

```bash theme={null}
-H "x-api-key: YOUR_API_KEY"
```

<Card title="Learn More" icon="key" href="/guides/authentication">
  See the Authentication guide for details on obtaining and using API keys.
</Card>

## Official SDKs

We interpret your request using our official open-source SDKs for Python and Node.js:

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="https://github.com/Audixa/audixa-python">
    `pip install audixa`
  </Card>

  <Card title="Node.js SDK" icon="node" href="https://github.com/Audixa/audixa-node">
    `npm install audixa`
  </Card>
</CardGroup>

## Async Workflow

Audixa uses an **asynchronous workflow** for audio generation:

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Audixa API
    participant CDN
    
    Client->>Audixa API: POST /v3/tts (text, voice, model)
    Audixa API-->>Client: 200 OK {generation_id, status: "IN_QUEUE"}
    
    loop Poll until complete
        Client->>Audixa API: GET /v3/tts?generation_id=...
        Audixa API-->>Client: {status: "GENERATING"}
    end
    
    Audixa API-->>Client: {status: "COMPLETED", audio_url: "..."}
    Client->>CDN: Download audio file
    CDN-->>Client: Audio file
```

<Steps>
  <Step title="Submit TTS Request">
    POST to `/v3/tts` with your text, voice, and model. Receive a `generation_id` and initial status `IN_QUEUE`.
  </Step>

  <Step title="Poll Status">
    GET `/v3/tts` with your `generation_id` until status is `COMPLETED`.
  </Step>

  <Step title="Download Audio">
    Fetch the audio file from the returned `audio_url`.
  </Step>
</Steps>

## Available Endpoints

<CardGroup cols={3}>
  <Card title="POST /tts" icon="play" href="/api-reference/tts">
    Start a text-to-speech generation job.
  </Card>

  <Card title="GET /tts (Status)" icon="clock" href="/api-reference/generation">
    Check the status of a generation job.
  </Card>

  <Card title="GET /voices" icon="users" href="/api-reference/voices">
    List available voices for a model.
  </Card>

  <Card title="GET /history" icon="list" href="/api-reference/history">
    Retrieve generation history.
  </Card>

  <Card title="WS /stream" icon="bolt" href="/api-reference/streaming">
    Real-time audio streaming.
  </Card>
</CardGroup>

## Response Format

All responses are JSON. Successful responses return status `2xx` with the requested data.

**Success example:**

```json theme={null}
{
  "generation_id": "gen_abc123xyz789"
}
```

**Error example:**

```json theme={null}
{
  "detail": "Error message explaining what went wrong"
}
```

## Quick Links

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first audio in 5 minutes.
  </Card>

  <Card title="Error Codes" icon="circle-exclamation" href="/guides/error-codes">
    Understand and handle API errors.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/guides/rate-limits">
    Learn about request limits and best practices.
  </Card>

  <Card title="Pricing" icon="coins" href="/guides/pricing-credits">
    Understand credit-based billing.
  </Card>
</CardGroup>