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

# Async

> Text-to-speech services using Async's WebSocket and HTTP APIs

## Overview

Async provides high-quality text-to-speech synthesis with two service implementations: `AsyncAITTSService` (WebSocket-based) for real-time streaming with interruption support, and `AsyncAIHttpTTSService` (HTTP-based) for simpler synthesis. `AsyncAITTSService` is recommended for interactive applications requiring low latency.

<CardGroup cols={2}>
  <Card title="AsyncAI TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.asyncai.tts.html">
    Pipecat's API methods for AsyncAI TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-asyncai.py">
    Complete example with WebSocket streaming
  </Card>

  <Card title="Async Documentation" icon="book" href="https://docs.async.ai/">
    Official Async API documentation
  </Card>

  <Card title="Voice Models" icon="microphone" href="https://async.ai/">
    Explore available voice models and features
  </Card>
</CardGroup>

## Installation

To use Async services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[asyncai]"
```

## Prerequisites

### Async Account Setup

Before using Async TTS services, you need:

1. **Async Account**: Sign up at [Async](https://async.ai)
2. **API Key**: Generate an API key from your account dashboard
3. **Voice Selection**: Choose from available voice models

### Required Environment Variables

* `ASYNCAI_API_KEY`: Your Async API key for authentication

## Configuration

### AsyncAITTSService

<ParamField path="api_key" type="str" required>
  Async API key.
</ParamField>

<ParamField path="voice_id" type="str" required deprecated>
  UUID of the voice to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=AsyncAITTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="model" type="str" default="async_flash_v1.0" deprecated>
  TTS model to use. *Deprecated in v0.0.105. Use
  `settings=AsyncAITTSService.Settings(model=...)` instead.*
</ParamField>

<ParamField path="version" type="str" default="v1">
  Async API version.
</ParamField>

<ParamField path="url" type="str" default="wss://api.async.com/text_to_speech/websocket/ws">
  WebSocket endpoint URL.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate.
</ParamField>

<ParamField path="encoding" type="str" default="pcm_s16le">
  Audio encoding format.
</ParamField>

<ParamField path="container" type="str" default="raw">
  Audio container format.
</ParamField>

<ParamField path="text_aggregation_mode" type="TextAggregationMode" default="TextAggregationMode.SENTENCE">
  Controls how incoming text is aggregated before synthesis. `SENTENCE`
  (default) buffers text until sentence boundaries, producing more natural
  speech. `TOKEN` streams tokens directly for lower latency. Import from
  `pipecat.services.tts_service`.
</ParamField>

<ParamField path="aggregate_sentences" type="bool" default="None" deprecated>
  *Deprecated in v0.0.104.* Use `text_aggregation_mode` instead.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=AsyncAITTSService.Settings(...)`
  instead.*
</ParamField>

<ParamField path="settings" type="AsyncAITTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### AsyncAIHttpTTSService

The HTTP service accepts similar parameters to the WebSocket service, with these differences:

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  An aiohttp session for HTTP requests. You must create and manage this
  yourself.
</ParamField>

<ParamField path="url" type="str" default="https://api.async.com">
  HTTP API base URL (instead of WebSocket URL).
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AsyncAITTSService.Settings(...)`. These can be updated mid-conversation with `TTSUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default | Description                            |
| ---------- | ----------------- | ------- | -------------------------------------- |
| `model`    | `str`             | `None`  | Model identifier. *(Inherited.)*       |
| `voice`    | `str`             | `None`  | Voice identifier. *(Inherited.)*       |
| `language` | `Language \| str` | `None`  | Language for synthesis. *(Inherited.)* |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.asyncai import AsyncAITTSService

tts = AsyncAITTSService(
    api_key=os.getenv("ASYNCAI_API_KEY"),
    settings=AsyncAITTSService.Settings(
        voice="your-voice-uuid",
    ),
)
```

### With Language Customization

```python theme={null}
from pipecat.transcriptions.language import Language

tts = AsyncAITTSService(
    api_key=os.getenv("ASYNCAI_API_KEY"),
    settings=AsyncAITTSService.Settings(
        voice="your-voice-uuid",
        model="async_flash_v1.0",
        language=Language.ES,
    ),
)
```

### HTTP Service

```python theme={null}
import aiohttp
from pipecat.services.asyncai import AsyncAIHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = AsyncAIHttpTTSService(
        api_key=os.getenv("ASYNCAI_API_KEY"),
        settings=AsyncAIHttpTTSService.Settings(
            voice="your-voice-uuid",
        ),
        aiohttp_session=session,
    )
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Event Handlers

Async TTS supports the standard [service connection events](/api-reference/server/events/service-events):

| Event                 | Description                         |
| --------------------- | ----------------------------------- |
| `on_connected`        | Connected to Async WebSocket        |
| `on_disconnected`     | Disconnected from Async WebSocket   |
| `on_connection_error` | WebSocket connection error occurred |

```python theme={null}
@tts.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Async")
```