Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.play.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide provides a step-by-step approach to using the PlayAI Text-to-Speech API to convert text into natural human-like sounding audio using the Async (non-streaming) API Endpoint. In this example, we’ll have Dialog 1.0 create a simple audio from the given input text.

​
Prerequisites

  • Access credentials (Secret key and User ID)
  • Development environment for your chosen programming language

​
Steps

1

Set Up Environment Variables

Add your API key and user ID to your environment variables.
echo 'export PLAYAI_API_KEY="your_api_key_here"' >> ~/.zshrc
echo 'export PLAYAI_USER_ID="your_user_id_here"' >> ~/.zshrc
source ~/.zshrc
2

Configure API Access

Create a script with the following authentication setup for your chosen language:
import os

api_key = os.getenv("PLAYAI_API_KEY")
user_id = os.getenv("PLAYAI_USER_ID")

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
    'X-USER-ID': user_id
}
3

Submit TTS Job

Create and submit your TTS job in your chosen language:
json_data = {
    'model': 'PlayDialog',
    'text': "This is the greatest moment to be alive",
    'voice': 's3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json',
    'outputFormat': 'mp3',
    'speed': 1,
    'language': 'english',
}

response = requests.post('https://api.play.ai/api/v1/tts',
                       headers=headers,
                       json=json_data)

if response.status_code == 201:
    job_id = response.json().get('id')
    print(f"Job submitted successfully. Job ID: {job_id}")
else:
    print(f"Job submission failed with status code {response.status_code}: {response.text}")
4

Poll Job Status

Monitor your job’s progress in your chosen language:
polling_url = f'https://api.play.ai/api/v1/tts/{job_id}'

while True:
    response = requests.get(polling_url, headers=headers)
    status = response.json()['output']['status']

    if status == 'COMPLETED':
        audio_url = response.json()['output']['url']
        print(f"Job completed. Audio URL: {audio_url}")
        break
    elif status == 'IN_PROGRESS':
        print("Job is still in progress. Retrying in 5 seconds...")
        time.sleep(5)
    else:
        print(f"Job failed or encountered an unknown status: {status}")
        break
5

Download and Save Audio

Save the generated audio file in your chosen language:
audio_url = response.json()['output']['url']
audio_response = requests.get(audio_url)

if audio_response.status_code == 200:
    with open('output.mp3', 'wb') as f:
        f.write(audio_response.content)
    print("Audio file saved as output.mp3")
else:
    print(f"Failed to download audio. Status code: {audio_response.status_code}")

​
Complete Code

import os
import requests
import time

api_key = os.getenv("PLAYAI_API_KEY")
user_id = os.getenv("PLAYAI_USER_ID")

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
    'X-USER-ID': user_id
}

# Submit TTS Job
json_data = {
    'model': 'PlayDialog',
    'text': "This is the greatest moment to be alive",
    'voice': 's3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json',
    'outputFormat': 'mp3',
    'speed': 1,
    'language': 'english',
}

response = requests.post('https://api.play.ai/api/v1/tts',
                       headers=headers,
                       json=json_data)

if response.status_code == 201:
    job_id = response.json().get('id')
    print(f"Job submitted successfully. Job ID: {job_id}")

    # Poll Job Status
    polling_url = f'https://api.play.ai/api/v1/tts/{job_id}'
    while True:
        response = requests.get(polling_url, headers=headers)
        status = response.json()['output']['status']

        if status == 'COMPLETED':
            audio_url = response.json()['output']['url']
            print(f"Job completed. Audio URL: {audio_url}")

            # Download Audio
            audio_response = requests.get(audio_url)
            if audio_response.status_code == 200:
                with open('output.mp3', 'wb') as f:
                    f.write(audio_response.content)
                print("Audio file saved as output.mp3")
            else:
                print(f"Failed to download audio. Status code: {audio_response.status_code}")
            break
        elif status == 'IN_PROGRESS':
            print("Job is still in progress. Retrying in 5 seconds...")
            time.sleep(5)
        else:
            print(f"Job failed or encountered an unknown status: {status}")
            break
else:
    print(f"Job submission failed with status code {response.status_code}: {response.text}")

​
Troubleshooting

If you encounter issues, check these common problems:
  • Authentication Issues:
    • Verify your API key and user ID
    • Confirm the AUTHORIZATION header includes “Bearer ” prefix
  • Job Status Polling:
    • Ensure you’re using the correct job ID
    • Check that the polling URL is properly formatted
    • Verify the polling interval is appropriate for your use case
  • API Endpoint Errors:
    • Verify the correct PlayAI’s Dialog 1.0 API endpoint URL
    • Confirm the model name is correct
    • Check that all required parameters are included in the request
  • Language-Specific Issues:
    • JavaScript: Ensure node-fetch is installed for Node.js environments
    • Go: Check for proper error handling and response body closing
    • Dart: Verify the http package is added to your pubspec.yaml
    • Swift: Make sure you’re running on macOS for file system access