> ## 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 Streaming Text to Speech

> <b>Asynchronous streaming text-to-speech for direct client delivery</b>

This endpoint initiates streaming text-to-speech synthesis and immediately returns a mediaId and token. 
Unlike regular async TTS, this enables chunked streaming with ~300ms first chunk latency when retrieved.

**When to use this endpoint:**
- **Frontend streaming** - Stream audio directly to browsers without proxy
- **Low-latency playback** - Start playing audio before full generation completes
- **CDN streaming** - Progressive download through content delivery networks
- **Mobile apps** - Reduce initial buffering time

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 audio streams progressively when retrieved via the /stream-audio endpoint.




## OpenAPI

````yaml post /synthesis/text-to-speech/stream-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/stream-async:
    post:
      summary: Async Streaming Text to Speech
      description: >
        <b>Asynchronous streaming text-to-speech for direct client delivery</b>


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

        Unlike regular async TTS, this enables chunked streaming with ~300ms
        first chunk latency when retrieved.


        **When to use this endpoint:**

        - **Frontend streaming** - Stream audio directly to browsers without
        proxy

        - **Low-latency playback** - Start playing audio before full generation
        completes

        - **CDN streaming** - Progressive download through content delivery
        networks

        - **Mobile apps** - Reduce initial buffering time


        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 audio streams progressively when retrieved via the /stream-audio
        endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechStreamAsyncRequest'
      responses:
        '200':
          description: Successfully initiated streaming 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: Streaming async TTS
          source: >
            import requests

            import json


            # Step 1: Initiate streaming async TTS

            url =
            "https://api.upliftai.org/v1/synthesis/text-to-speech/stream-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: Stream audio with ~300ms first chunk

            media_id = result['mediaId']

            token = result['token']


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


            # This URL supports chunked streaming

            # First chunk arrives in ~300ms
        - lang: JavaScript
          label: Frontend streaming
          source: |
            // Initiate streaming TTS
            async function streamAudio(text) {
              const response = await fetch('https://api.upliftai.org/v1/synthesis/text-to-speech/stream-async', {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json',
                  'Authorization': 'Bearer YOUR_API_KEY'
                },
                body: JSON.stringify({
                  voiceId: "v_meklc281",
                  text: text,
                  outputFormat: "MP3_22050_128"
                })
              });
              
              const { mediaId, token } = await response.json();
              const streamUrl = `https://api.upliftai.org/v1/synthesis/stream-audio/${mediaId}?token=${token}`;
              
              // Create audio element that starts streaming
              const audio = new Audio(streamUrl);
              audio.play(); // Starts playing as chunks arrive
              
              return audio;
            }
components:
  schemas:
    TextToSpeechStreamAsyncRequest:
      type: object
      required:
        - text
        - outputFormat
      description: Request for asynchronous streaming 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
            - ULAW_8000_8
          description: >-
            Format of the output audio. Wav files are usually 10x larger, we
            recommend using MP3 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_..."

````