## Overview

Orator is our specialized TTS API that delivers natural-sounding voice synthesis for Pakistani languages. It handles native pronunciation, mixed language text, and cultural nuances that generic TTS services miss.

### Why Orator?

## Native Urdu Pronunciation

Trained on authentic Urdu speech patterns, not transliterations

## Mixed Language Support

Seamlessly handles Urdu-English code-switching common in conversation

## Cultural Voice Profiles

Multiple voices matching regional preferences and use cases

## Developer-First API

Simple REST & WebSocket APIs with comprehensive SDKs

## Quick Start

### 1. Get Your API Key

1. Sign Up
   
   Visit [upliftai.org](/content/site-root.html) to create your account  
2. Generate Key
   
   Navigate to API Keys section and click “Generate New Key”
3. Make your AI speak like a Pakistani

### 2. Make Your First Request

Once you have your API key, you can make your first text-to-speech request. Here’s a simple example using JavaScript:

```
async function convertTextToSpeech() {
  try {
    const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_api_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        "voiceId": "v_8eelc901", // See available voice Ids in the documentation below
        "text": "سلام، آپ اِس وقت اوریٹر کی آواز سن رہے ہیں۔", // => "Salaam, Aap ise waqt Orator ki awaaz suun rahay hain."
        "outputFormat": "MP3_22050_128"
      })
    });

// Get audio duration from headers
    const audioDuration = response.headers.get('x-uplift-ai-audio-duration');
    console.log(`Audio duration: ${audioDuration}ms`);

// The response body is an audio blob, you can save this or send it to your frontend to be played
    const audioBlob = await response.blob();

} catch (error) {
    console.error('Error:', error);
  }
}

// Call the function
convertTextToSpeech();
```

### 3. Best Practices for Urdu Text

**Pro Tip**: Test your text in small chunks first to ensure proper pronunciation before processing large documents.

| Text Type | Recommendation | Example |
| --- | --- | --- |
| Pure Urdu | Use Urdu script | آپ کیسے ہیں؟ میں ٹھیک ہوں۔ |
| English in Urdu | Keep in ASCII | یہ ایک exerted force ہے |
| Numbers | Use Western numerals | 2024 instead of ۲۰۲۴ |
| Brands | Use official spelling | WhatsApp, not واٹس ایپ |

## Advanced Features

### Phrase Replacement for Perfect Pronunciation

Perfect for handling:

- **Brand names**: Convert English spellings to Urdu phonetics
- **Technical terms**: Ensure consistent pronunciation
- **LLM outputs**: Fix common misspellings from AI models
- **Regional variations**: Adapt to local dialects

For example:

```
[
  {"phrase":"سیونگز اکاؤنٹ","replacement":"savings account"},
  // In Urdu Isabion is pronunced Izabiyan, but LLMs don't understand this
  {"phrase":"Isabion","replacement":"ایزابیان"},
  // Sometimes the English spellings of brand names don't capture Urdu pronunciation
  {"phrase": "Meezan bank", "replacement": "میزان بینک"}
]
```

Here is how you can create a replacement configuration:

```javascript
// Create a phrase replacement configuration
async function createPhraseReplacements() {
  try {
    const response = await fetch('https://api.upliftai.org/v1/synthesis/phrase-replacement-config', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_api_your_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        "phraseReplacements": [
          {
            "phrase": "سیونگز اکاؤنٹ",
            "replacement": "Savings account",
          },
          {
            "phrase": "Meezan bank",
            "replacement": "میزان بینک"
          }
        ]
      })
    });

const data = await response.json();
    console.log('Configuration created with ID:', data.configId);
    return data.configId; // save this configId for later reuse
  } catch (error) {
    console.error('Error creating phrase replacements:', error);
  }
}

// Use the configuration ID in your text-to-speech request
async function ttsWithPhraseReplacement(configId) {
  // Similar to the first example, but add phraseReplacementConfigId
  const requestBody = {
    "voiceId": "v_8eelc901",
    "text": "Meezan Bank اعتماد کا ضامن",
    "outputFormat": "MP3_22050_128",
    "phraseReplacementConfigId": configId
  };

// Make API request as shown in the first example
}
```

## Voice Profiles

Each voice is optimized for specific use cases and audiences:

**Info/Education**: `voiceId: "v_8eelc901"` Listen to articles, information, and videos. Fast and easy to understand.  
**Nostalgic News**: `voiceId: "v_30s70t3a"` A classic Pakistani news voice that we heard growing up. We bring those memories back. Stay calm, stay tuned.  
**Dada Jee**: `voiceId: "v_yypgzenx"` Listen to stories with a suspensful and deep voice.  
**Gen Z** (under development): `voiceId: "v_kwmp7zxt"` If you want your info clean and fast, this voice is for you.  
For more voices and languages check [this voices page](https://docs.upliftai.org/orator_voices)

## Common Use Cases

## Customer Support Bots

Make WhatsApp agents that respond to voice. Make real-time customer support over calls.

## Educational Content

Farming advisory, simple medical FAQs i.e “Sar dardh k liye kia karoun” -> respond in voice

## News Broadcasting

News & blogs can offer Urdu play buttons that will play the audio

## Interactive Stories

Make captivating stories

## Error Handling

```
try {
  const response = await fetch(TTS_ENDPOINT, options);

if (!response.ok) {
    const error = await response.json();
    switch(response.status) {
      case 400:
        console.error('Invalid request:', error.message);
        break;
      case 401:
        console.error('Invalid API key');
        break;
      case 429:
        console.error('Rate limit exceeded, retry after:',
          response.headers.get('Retry-After'));
        break;
      case 500:
        console.error('Server error, please retry');
        break;
    }
  }
} catch (error) {
  console.error('Network error:', error);
}
```

## Need Help?

[**API Reference** 
\ Complete endpoint documentation](https://docs.upliftai.org/api-reference/endpoint/text-to-speech)

[**WebSocket Guide** 
\ Real-time streaming setup](https://docs.upliftai.org/websocket-tts)

[**Contact Support** 
\ Get help with integration](mailto:founders@upliftai.org)