> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart Guide
> High-quality Pakistani text-to-speech with natural pronunciation
## 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?
Trained on authentic Urdu speech patterns, not transliterations
Seamlessly handles Urdu-English code-switching common in conversation
Multiple voices matching regional preferences and use cases
Simple REST & WebSocket APIs with comprehensive SDKs
## Quick Start
### 1. Get Your API Key
Visit [upliftai.org](https://upliftai.org) to create your account
Navigate to API Keys section and click "Generate New Key"
### 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:
```javascript theme={null}
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:
```json theme={null}
[
{"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 theme={null}
// 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:
export const DisplayAudio = ({audio_url}) => ;
**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 langauges check [this voices page](/orator_voices)
## Common Use Cases
Make whatsapp agents that respond to in voice. Make real time customer support over call.
Farming advisory, simple medical FAQs i.e "Sar dardh k liye kia karoun" -> respond in voice
News & blogs can offer Urdu play buttons that will play the audio
Make captivating stories
## Error Handling
```javascript theme={null}
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?
Complete endpoint documentation
Real-time streaming setup
Get help with integration
