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

# Async Text to Speech

> <b>Asynchronous text-to-speech synthesis for bot and server-side workflows</b>

This endpoint initiates text-to-speech synthesis and immediately returns a mediaId and token. 
The audio is generated asynchronously and can be retrieved using the returned credentials.

**When to use this endpoint:**
- **Bot integrations** (WhatsApp, Telegram, etc.) - Avoid audio passing through your system
- **Webhook workflows** - When you need to process audio generation separately
- **Batch processing** - When converting multiple texts without blocking
- **Direct client delivery** - Let clients fetch audio directly using the secure token

For best results with Urdu, use Urdu script. For English words within Urdu text, use ASCII characters.
Example: "<span dir="rtl" class="urdu">یہ ایک exerted force ہے</span>"

The generated audio URL can be shared directly with end users or services without proxying through your server.




## OpenAPI

````yaml post /synthesis/text-to-speech-async
openapi: 3.1.0
info:
  title: UpliftAI API
  version: 1.0.0
  description: >
    API for UpliftAI messaging, media handling, and text-to-speech capabilities.
    This API enables real-time communication

    with AI assistants, supporting various content types including text, images,
    audio,

    and documents. It provides both synchronous and asynchronous messaging
    capabilities

    with webhook support for real-time updates. The API also supports
    text-to-speech synthesis

    and phrase replacement configuration.
servers:
  - url: https://api.upliftai.org/v1
    description: Version 1 API
security: []
paths:
  /synthesis/text-to-speech-async:
    post:
      summary: Async Text to Speech
      description: >
        <b>Asynchronous text-to-speech synthesis for bot and server-side
        workflows</b>


        This endpoint initiates text-to-speech synthesis and immediately returns
        a mediaId and token. 

        The audio is generated asynchronously and can be retrieved using the
        returned credentials.


        **When to use this endpoint:**

        - **Bot integrations** (WhatsApp, Telegram, etc.) - Avoid audio passing
        through your system

        - **Webhook workflows** - When you need to process audio generation
        separately

        - **Batch processing** - When converting multiple texts without blocking

        - **Direct client delivery** - Let clients fetch audio directly using
        the secure token


        For best results with Urdu, use Urdu script. For English words within
        Urdu text, use ASCII characters.

        Example: "<span dir="rtl" class="urdu">یہ ایک exerted force ہے</span>"


        The generated audio URL can be shared directly with end users or
        services without proxying through your server.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechAsyncRequest'
      responses:
        '200':
          description: Successfully initiated audio synthesis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextToSpeechAsyncResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid request parameters
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Rate limit exceeded, please try again later
      security:
        - apiKeyAuth: []
      x-codeSamples:
        - lang: Python
          label: Async TTS with retrieval
          source: >
            import requests

            import json


            # Step 1: Initiate async TTS

            url = "https://api.upliftai.org/v1/synthesis/text-to-speech-async"


            payload = json.dumps({
              "voiceId": "v_meklc281",
              "text": "سلام، یہ پاکستان کی تاریخ کے بارے میں ہے۔",
              "outputFormat": "MP3_22050_128"
            })

            headers = {
              'Content-Type': 'application/json',
              'Authorization': 'Bearer YOUR_API_KEY'
            }


            response = requests.post(url, headers=headers, data=payload)

            result = response.json()


            # Step 2: Retrieve audio when ready

            media_id = result['mediaId']

            token = result['token']


            audio_url =
            f"https://api.upliftai.org/v1/synthesis/stream-audio/{media_id}?token={token}"


            # Get the audio

            audio_response = requests.get(audio_url)


            # Save to file

            with open('output.mp3', 'wb') as f:
                f.write(audio_response.content)
        - lang: JavaScript
          label: Direct client retrieval
          source: |
            // Server-side: Initiate TTS
            async function initiateTTS() {
              const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech-async', {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                  'Authorization': 'Bearer YOUR_API_KEY'
                },
                body: JSON.stringify({
                  voiceId: "v_meklc281",
                  text: "سلام، یہ پاکستان کی تاریخ کے بارے میں ہے۔",
                  outputFormat: "MP3_22050_128"
                })
              });
              
              const { mediaId, token } = await response.json();
              
              // Send URL to client or webhook
              const audioUrl = `https://api.upliftai.org/v1/synthesis/stream-audio/${mediaId}?token=${token}`;
              
              // Client can now fetch audio directly
              return audioUrl;
            }
components:
  schemas:
    TextToSpeechAsyncRequest:
      type: object
      required:
        - text
        - outputFormat
      description: Request for asynchronous text-to-speech synthesis
      properties:
        voiceId:
          type: string
          description: >
            Identifier for the voice to use.

            Named voices: v_meklc281 (Urdu female), v_8eelc901 (Info/Edu),
            v_kwmp7zxt (Gen Z), v_yypgzenx (Dada Jee), v_30s70t3a (Nostalgic
            News)
          example: v_meklc281
        text:
          type: string
          maxLength: 2500
          description: The text to synthesize
          example: سلام، آپ اِس وقت اوریٹر کی آواز سن رہے ہیں۔
        outputFormat:
          type: string
          enum:
            - PCM_22050_16
            - WAV_22050_16
            - WAV_22050_32
            - MP3_22050_32
            - MP3_22050_64
            - MP3_22050_128
            - OGG_22050_16
            - ULAW_8000_8
          description: >-
            Format of the output audio. Wav files are usually 10x larger, we
            recommend using MP3 or OGG for best compression results while
            maintaining quality.
        phraseReplacementConfigId:
          type: string
          description: Optional ID of a phrase replacement configuration to apply
    TextToSpeechAsyncResponse:
      type: object
      description: Response containing mediaId and token for retrieving synthesized audio
      properties:
        mediaId:
          type: string
          description: Unique identifier for the generated audio media
          example: media_abc123xyz
        token:
          type: string
          description: JWT token for secure retrieval of the audio
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key with format "Bearer sk_api_..."

````