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

# Audio

> Convert text to speech with natural-sounding voices

The `tts()` method converts text into spoken audio using AI voice models from OpenAI, ElevenLabs, and other providers.

## Basic Text-to-Speech

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Hello! Welcome to Verlon AI text-to-speech.'
  }
});

console.log('Audio URL:', response.audio.url);
console.log('Duration:', response.audio.duration, 'seconds');
console.log('Cost:', response.cost);
```

## Voice Selection

Choose from different voices:

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'The weather today is sunny and warm.',
    voice: 'alloy'  // Options: alloy, echo, fable, onyx, nova, shimmer
  }
});
```

### Available Voices

| Voice     | Characteristics     |
| --------- | ------------------- |
| `alloy`   | Neutral, balanced   |
| `echo`    | Clear, professional |
| `fable`   | Warm, storytelling  |
| `onyx`    | Deep, authoritative |
| `nova`    | Energetic, friendly |
| `shimmer` | Soft, calm          |

<Tip>
  Try different voices to find the best match for your content. Use `alloy` or `echo` for professional content, `fable` for narratives, and `nova` for upbeat messages.
</Tip>

## Audio Format

Control the output audio format:

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Sample text',
    responseFormat: 'mp3'  // mp3, opus, aac, flac, wav, pcm
  }
});
```

### Format Options

| Format | Quality   | Size       | Use Case                   |
| ------ | --------- | ---------- | -------------------------- |
| `mp3`  | Good      | Small      | General use, streaming     |
| `opus` | Great     | Very small | Web, low bandwidth         |
| `aac`  | Good      | Small      | Mobile apps                |
| `flac` | Excellent | Large      | High quality, archival     |
| `wav`  | Perfect   | Very large | Professional audio editing |
| `pcm`  | Perfect   | Largest    | Raw audio processing       |

## Speech Speed

Adjust playback speed:

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'This will be spoken at different speeds.',
    speed: 1.25  // 0.25 to 4.0
  }
});
```

### Speed Guide

| Speed  | Use Case                   |
| ------ | -------------------------- |
| `0.5`  | Very slow, educational     |
| `0.75` | Slow, clear pronunciation  |
| `1.0`  | Normal speed (default)     |
| `1.25` | Slightly faster, energetic |
| `1.5`  | Fast, time-saving          |
| `2.0+` | Very fast, previews        |

<Note>
  Speeds below 0.5 or above 2.0 may sound unnatural. Stick to 0.75-1.5 for most use cases.
</Note>

## Parameters

### Request Parameters

| Parameter        | Type     | Default       | Description               |
| ---------------- | -------- | ------------- | ------------------------- |
| `input`          | `string` | Required      | Text to convert to speech |
| `voice`          | `string` | Model default | Voice to use              |
| `speed`          | `number` | 1.0           | Playback speed (0.25-4.0) |
| `responseFormat` | `string` | `mp3`         | Audio format              |

## Response

```typescript theme={null}
interface AudioResponse {
  id: string;                    // Request ID
  model: string;                 // Model used
  audio: AudioOutput;            // Audio data
  cost: number;                  // Request cost in USD
  latency: number;               // Response time in ms
}

interface AudioOutput {
  url?: string;                  // Hosted audio URL
  base64?: string;               // Base64-encoded audio
  format?: string;               // Audio format
  duration?: number;             // Length in seconds
}
```

## Best Practices

### 1. Format Text for Speech

```typescript theme={null}
// Good ✅ - Natural speech patterns
{
  input: 'Hello, and welcome to our podcast. Today we\'re discussing AI.'
}

// Less natural - Missing punctuation
{
  input: 'hello and welcome to our podcast today were discussing AI'
}
```

### 2. Use SSML for Control

Some models support SSML (Speech Synthesis Markup Language):

```typescript theme={null}
{
  input: '<speak>Hello! <break time="500ms"/> This is a pause.</speak>'
}
```

### 3. Choose Appropriate Format

```typescript theme={null}
// Good ✅ - MP3 for web playback
{
  input: 'Website announcement',
  responseFormat: 'mp3'
}

// Good ✅ - FLAC for podcast production
{
  input: 'Podcast episode narration',
  responseFormat: 'flac'
}
```

### 4. Always Handle Errors

```typescript theme={null}
try {
  const response = await verlon.tts({
    gateId: 'your-gate-id',
    data: {
      input: 'Sample text'
    }
  });

  return response.audio.url;
} catch (error) {
  console.error('TTS generation failed:', error);
  return null;
}
```

### 5. Monitor Costs

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: longText
  }
});

console.log(`Duration: ${response.audio.duration}s`);
console.log(`Cost: $${response.cost.toFixed(6)}`);
console.log(`Characters: ${longText.length}`);
```

## Examples

### Podcast Intro

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  metadata: { type: 'podcast-intro' },
  data: {
    input: 'Welcome to Tech Talks, the podcast where we explore the latest in technology and innovation.',
    voice: 'fable',
    responseFormat: 'mp3',
    speed: 1.0
  }
});
```

### Product Announcement

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Introducing our new flagship product, designed to revolutionize your workflow!',
    voice: 'nova',
    speed: 1.1
  }
});
```

### Educational Content

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'In this lesson, we will learn about photosynthesis, the process by which plants convert sunlight into energy.',
    voice: 'echo',
    speed: 0.9,  // Slower for learning
    responseFormat: 'mp3'
  }
});
```

### Audiobook Narration

```typescript theme={null}
const chapter = `
  Chapter One: The Beginning.

  It was a dark and stormy night. The wind howled through the trees,
  and rain pounded against the windows of the old mansion.
`;

const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: chapter,
    voice: 'fable',
    responseFormat: 'flac',  // High quality for production
    speed: 1.0
  }
});
```

### Voice Assistant Response

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Your package will arrive tomorrow between 2 and 4 PM.',
    voice: 'alloy',
    responseFormat: 'opus',  // Small file for quick delivery
    speed: 1.0
  }
});
```

### Multilingual Content

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Bonjour! Comment allez-vous?',
    voice: 'shimmer'
  }
});
```

## Advanced Usage

### Batch Generation

Generate multiple audio files:

```typescript theme={null}
const scripts = [
  'Welcome to the tour.',
  'This is the main lobby.',
  'Here is the conference room.',
  'Thank you for visiting!'
];

const audioFiles = await Promise.all(
  scripts.map(text =>
    verlon.tts({
      gateId: 'your-gate-id',
      data: {
        input: text,
        voice: 'echo'
      }
    })
  )
);

audioFiles.forEach((response, i) => {
  console.log(`Audio ${i + 1}:`, response.audio.url);
});
```

### Download Audio File

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Hello world',
    responseFormat: 'mp3'
  }
});

// Download to local file
const audioData = await fetch(response.audio.url);
const buffer = await audioData.arrayBuffer();
await fs.writeFile('output.mp3', Buffer.from(buffer));
```

### Base64 Audio Embedding

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Sample text',
    responseFormat: 'mp3'
  }
});

// Use base64 in HTML
const audioHTML = `
  <audio controls>
    <source src="${response.audio.base64}" type="audio/mpeg">
  </audio>
`;
```

### Override Model

Use a specific TTS model:

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  model: 'tts-1-hd',  // High-quality model
  data: {
    input: 'Premium audio content'
  }
});
```

### Custom Metadata

Track TTS generation:

```typescript theme={null}
const response = await verlon.tts({
  gateId: 'your-gate-id',
  metadata: {
    userId: 'user-123',
    feature: 'voiceover',
    language: 'en-US'
  },
  data: {
    input: 'Sample narration'
  }
});
```

## Use Cases

### E-Learning Platforms

Convert course content to audio for accessibility:

```typescript theme={null}
const lesson = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: courseText,
    voice: 'echo',
    speed: 0.9,
    responseFormat: 'mp3'
  }
});
```

### IVR Systems

Generate prompts for phone systems:

```typescript theme={null}
const greeting = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: 'Thank you for calling. Press 1 for sales, press 2 for support.',
    voice: 'alloy',
    responseFormat: 'wav'
  }
});
```

### Content Creation

Add voiceovers to videos:

```typescript theme={null}
const narration = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: videoScript,
    voice: 'fable',
    responseFormat: 'flac'
  }
});
```

### Accessibility

Make written content accessible:

```typescript theme={null}
const audioVersion = await verlon.tts({
  gateId: 'your-gate-id',
  data: {
    input: articleText,
    voice: 'echo',
    speed: 1.0,
    responseFormat: 'mp3'
  }
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Video" icon="video" href="/sdk-reference/video">
    Add audio to video content
  </Card>

  <Card title="Chat" icon="comments" href="/sdk-reference/chat">
    Generate text for TTS
  </Card>

  <Card title="Gates & Routing" icon="route" href="/concepts/gates-and-routing">
    How Verlon routes TTS requests
  </Card>

  <Card title="Cost Tracking" icon="chart-line" href="/concepts/cost-tracking">
    Monitor TTS costs
  </Card>
</CardGroup>