Quickstart Guide - Uplift AI API Docs

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 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.

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:

// 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

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

WebSocket Guide \ Real-time streaming setup

Contact Support \ Get help with integration