Play.ht API

Introduction

The Play.ht API allows you to integrate state-of-the-art AI voices in almost every language and accent in the world into your applications.

Here are some benefits of using our API:

• You maintain a single API integration to access all the world's leading AI voices provided by Play.ht, Google, Amazon, IBM, and Microsoft.
• Any updates, improvements, new features, or voices that are added to these TTS engines will be automatically made available to you via this API.

Let's help you get things up and running!

Note: You need to have a Play.ht account with word credit to be able to access the API.

AI voices

This API provides a single interface to access all the ultra realistic voices powered by Peregrine, our very own generative speech model, and all the voices listed on our text-to-speech voices page powered by leading TTS engines in the world.

• Here's a list of all Utra-Realistic API voices.
• Here's a list of all Standard API voices.

Authentication

All endpoints require authentication. Authentication consists of two required HTTPS headers:

• Authorization: This is where your secret key goes.
• X-User-ID: This is where your Play.ht user ID goes.

To get your authentication credentials, log in to your Play.ht dashboard and visit the API section.

Note: Never share your secret key with anyone and never use your secret key in the front-end part of your application or in the browser.

If you're facing issues finding your credentials, please reach out to us at support@play.ht

Webhook Implementation

Register Webhook

The endpoint on the API that you will use to convert text to speech:

1. /convert: this endpoint performs a text-to-speech conversion.

Rate Limit & Support

• We support 50 request/min (this can be increased on request)
• The Webhook is available for Standard, Premium and Ultrarealistic voices.

Webhook Events / Status

1. CREATED
2. QUEUED
3. INPROGRESS
4. SUCCESS
5. FAILED

Webhook Sample Response Payload

• QUEUED Status jsonc { status: 'QUEUED', voice: 'en-US-MichelleNeural', requestId: '7b0d977f-2c23-4468-9989-3545240b6c4e', metadata: { progress: 0 } }
• SUCCESS Status { status: 'SUCCESS', voice: 'en-US-MichelleNeural', requestId: '7b0d977f-2c23-4468-9989-3545240b6c4e', metadata: { progress: 100, output: [ 'https://peregrine-staging-results.s3.us-east-2.amazonaws.com/results/7b0d977f-2c23-4468-9989-3545240b6c4e_0.wav' ] } }

Convert text to speech

• Endpoint: ./convert

Use this endpoint to start converting an article from text to audio.

• Method: POST

• Body (JSON):

  {
    "voice": string,
    "content": string[],
    "ssml": string[],
    "title": string,          // Optional
    "narrationStyle": string, // Optional
    "globalSpeed": string,    // Optional
    "pronunciations": { key: string, value: string }[], // Optional
    "trimSilence": boolean,   // Optional
    "transcriptionId": string  // Optional - use it to update the same audio file
  }

• voice is the ID of the voice used to synthesize the text. Refer to the Voices reference file for more details.

note Only one of content or ssml can be passed:

• content is an array of strings, where each string represents a paragraph in plain text format.

• ssml is an array of strings, where each string represents a paragraph in SSML format. Learn more about SSML. Not all SSML features are supported with all voices.

• title is a field to name your file. You can use this name to find the audio in your Play.ht dashboard.

• narrationStyle is a string representing the tone and accent of the voice to read the text. Make sure the value for narrationStyle is supported by the voice in your request. Refer to the Voices reference file for more details.

• globalSpeed is a string in the format <number>%, where <number> is in the closed interval of [20, 200]. Use this to speed-up, or slow-down the speaking rate of the speech.

• pronunciations is an array of key-value pair objects, where key is the source string (e.g. "Play.ht"), and value is the target pronunciation (e.g. "Play dot H T"). Use this when you want to customize the pronunciation of a certain word/phrase (e.g. your brand name).

• trimSilence is a boolean value. When enabled, the audio will be trimmed to remove any silence from the end of the file.

• transcriptionId - Pass this to update an existing audio file

  • Response (JSON):

  {
    "status": "CREATED" | "error",
    "transcriptionId": string,
    "error": string // Optional
  }

Optional fields are only provided when applicable.

• Examples (cURL Request):

  curl --location --request POST 'https://play.ht/api/v1/convert' \
  --header 'Authorization: **************' \
  --header 'X-User-ID: ***************' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "voice": "en-US-MichelleNeural",
  "ssml": ["<speak><p>Hello my fried <break time=\"0.5s\"/></p></speak>"],
  "title": "Testing public api convertion"
  }'

• Example (Python Request):

  import requests
  import json

  url = "https://play.ht/api/v1/convert"

  payload = json.dumps({
    "voice": "en-US-MichelleNeural",
    "content": [
     "Hello My frinedsss",
     "either pass content s an array of strings , or ssml , but not both"
    ],
     "title": "Testing public api convertion"
  })
  headers = {
    'Authorization': '******************',
    'X-User-ID': '**************',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)
  print(response.text)

• Example (PHP - pecl_http):

  <?php
  $client = new http\Client;
  $request = new http\Client\Request;
  $request->setRequestUrl('https://play.ht/api/v1/convert');
  $request->setRequestMethod('POST');
  $body = new http\Message\Body;
  $body->append('{
    "voice": "en-US-MichelleNeural",
    "ssml": ["<speak><p>Hello my fried <break time=\"0.5s\"/></p></speak>",
        "<speak><p>--BEGIN-PLAYHT-CUSTOM-VOICE--en-US-AmberNeural--END-PLAYHT-CUSTOM-VOICE--How are you doing</p></speak>"],
    "title": "Testing public api convertion"
  }');
  $request->setBody($body);
  $request->setOptions(array());
  $request->setHeaders(array(
    'Authorization' => '*******************',
    'X-User-ID' => '***************',
    'Content-Type' => 'application/json'
  ));
  $client->enqueue($request)->send();
  $response = $client->getResponse();
  echo $response->getBody();

Base URL

• Base URL: https://play.ht/api/v1/

Notes:

• All endpoints are relative to the base URL.
• Requests should always be in JSON format, with a Content-Type: application/json header.

Standard API

Overview of API

There are two endpoints on the API that you will use to convert text to speech:

1. /convert: this endpoint performs a text-to-speech conversion.
2. /articleStatus: this endpoint lets you know if the conversion is done. (This would be deprecated in 30days Please migrate to webhook implementation)

Since the text-to-speech conversion is an asynchronous process, you will first make a POST request to the /convert endpoint with the text and voice, and then make GET requests to the /articleStatus endpoint to check if the conversion is done and to get the audio file.

The two endpoints have been described in detail below.

Standard API Endpoints

Convert text to speech

• Endpoint: ./convert

Use this endpoint to start converting an article from text to audio.

• Method: POST

• Body (JSON):

  {
    "voice": string,
    "content": string[],
    "ssml": string[],
    "title": string,          // Optional
    "narrationStyle": string, // Optional
    "globalSpeed": string,    // Optional
    "pronunciations": { key: string, value: string }[], // Optional
    "trimSilence": boolean,   // Optional
    "transcriptionId": string  // Optional - use it to update the same audio file
  }

• voice is the ID of the voice used to synthesize the text. Refer to the Voices reference file for more details.

note Only one of content or ssml can be passed:

• content is an array of strings, where each string represents a paragraph in plain text format.

• ssml is an array of strings, where each string represents a paragraph in SSML format. Learn more about SSML. Not all SSML features are supported with all voices.

• title is a field to name your file. You can use this name to find the audio in your Play.ht dashboard.

• narrationStyle is a string representing the tone and accent of the voice to read the text. Make sure the value for narrationStyle is supported by the voice in your request. Refer to the Voices reference file for more details.

• globalSpeed is a string in the format <number>%, where <number> is in the closed interval of [20, 200]. Use this to speed-up, or slow-down the speaking rate of the speech.

• pronunciations is an array of key-value pair objects, where key is the source string (e.g. "Play.ht"), and value is the target pronunciation (e.g. "Play dot H T"). Use this when you want to customize the pronunciation of a certain word/phrase (e.g. your brand name).

• trimSilence is a boolean value. When enabled, the audio will be trimmed to remove any silence from the end of the file.

• transcriptionId - Pass this to update an existing audio file

  • Response (JSON):

  {
    "status": "CREATED" | "error",
    "transcriptionId": string,
    "error": string // Optional
    "contentLength": number,
    "wordCount": number
  }

Use the transcriptionId in the response to check the conversion status in the Article status endpoint.

Transcription status

• Endpoint: ./articleStatus?transcriptionId={transcriptionId}

Use this endpoint to check the conversion status of your text using its transcription ID.

This endpoint would be deprecated and shutdown in 30days please migrate to the webhook implementation.Register Webhook

If the article (text) is converted to audio, the response will contain the audio file URL along with certain metadata such as voice and narration style. A true value for error field indicates a conversion failure.

Where {transcriptionId} is the ID provided in the successful response of Convert endpoint.

• Method: GET

• Response (JSON):

  {
    "converted": boolean,
    "error": boolean,         // Optional
    "errorMessage": string,   // Optional
    "audioUrl": string,       // Optional
    "audioDuration": number,  // Optional
    "voice": string,          // Optional
    "narrationStyle": string, // Optional
    "globalSpeed": string,    // Optional
  }

Optional fields are only provided when applicable.

• Examples (cURL Request):

  curl --location --request POST 'https://play.ht/api/v1/convert' \
  --header 'Authorization: **************' \
  --header 'X-User-ID: ***************' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "voice": "en-US-MichelleNeural",
  "ssml": ["<speak><p>Hello my fried <break time=\"0.5s\"/></p></speak>"],
  "title": "Testing public api convertion"
  }'

• Example (Python Request):

  import requests
  import json

  url = "https://play.ht/api/v1/convert"

  payload = json.dumps({
    "voice": "en-US-MichelleNeural",
    "content": [
     "Hello My frinedsss",
     "either pass content s an array of strings , or ssml , but not both"
    ],
     "title": "Testing public api convertion"
  })
  headers = {
    'Authorization': '******************',
    'X-User-ID': '**************',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)
  print(response.text)

• Example (PHP - pecl_http):

  <?php
  $client = new http\Client;
  $request = new http\Client\Request;
  $request->setRequestUrl('https://play.ht/api/v1/convert');
  $request->setRequestMethod('POST');
  $body = new http\Message\Body;
  $body->append('{
    "voice": "en-US-MichelleNeural",
    "ssml": ["<speak><p>Hello my fried <break time=\"0.5s\"/></p></speak>",
        "<speak><p>--BEGIN-PLAYHT-CUSTOM-VOICE--en-US-AmberNeural--END-PLAYHT-CUSTOM-VOICE--How are you doing</p></speak>"],
    "title": "Testing public api convertion"
  }');
  $request->setBody($body);
  $request->setOptions(array());
  $request->setHeaders(array(
    'Authorization' => '*******************',
    'X-User-ID' => '***************',
    'Content-Type' => 'application/json'
  ));
  $client->enqueue($request)->send();
  $response = $client->getResponse();
  echo $response->getBody();

Utra-Realistic API [beta]

Overview of Utra-Realistic API

There is only one endpoint on the API that you will use to convert text to speech:

• /convert: this endpoint performs a text-to-speech conversion.

Since the text-to-speech conversion is an asynchronous process, you will first make a POST request to the /convert endpoint with the text and voice, and then make GET requests to the S3 bucket URL returned by the /convert endpoint to check if the conversion is done and to get the audio file.

The endpoint has been described in detail below.

Convert text to speech

• Endpoint: ./convert

Use this endpoint to start converting an article from text to audio. ( This is available for both standard , Premium and Ultra Realistic Voices)

• Method: POST

• Body (JSON):

  {
    "voice": string,
    "content": string[],
    "title": string, // Optional
    "speed": string, // Optional
    "preset": string // Optional
  }

• voice is the name of the voice used to synthesize the text. Refer to the Voices reference file for more details.

• content is an array of strings, where each string represents a paragraph in plain text format.

• speed this controls how fast the output would be ranges from 0.5 - 1.5.

• preset this controls the quality of the output audio, 'real-time', 'high-quality'.

  • Response (JSON):

{
    "status": "CREATED",
    "transcriptionId": "-NNG-dZjRBIVTYkTlsz6",
    "contentLength": 1,
    "wordCount": 12

}

Responses and Updates for each request are available via the webhook, has this makes it easier for development and avoids long polling..

Utra-Realistic Examples

• Examples (cURL Request):

  curl --location --request POST 'https://play.ht/api/v1/convert' \
  --header 'Authorization: **************' \
  --header 'X-User-ID: ***************' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "voice": "Larry",
  "content": ["Hello world"]
  }'

• Example (Python Request):

  import requests
  import json

  url = "https://play.ht/api/v1/convert"

  payload = json.dumps({
    "voice": "Larry",
    "content": [
     "Hello My friends",
     "It's a beautiful day, isn't it ?"
    ],
    "speed": "1.0",
    "preset": "balanced"
  })
  headers = {
    'Authorization': '******************',
    'X-User-ID': '**************',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)
  print(response.text)

• Example (PHP - pecl_http):

  <?php
  $client = new http\Client;
  $request = new http\Client\Request;
  $request->setRequestUrl('https://play.ht/api/v1/convert');
  $request->setRequestMethod('POST');
  $body = new http\Message\Body;
  $body->append('{
    "voice": "Larry",
    "content": ["Hello my fried", "How are you doing"],
  }');
  $request->setBody($body);
  $request->setOptions(array());
  $request->setHeaders(array(
    'Authorization' => '*******************',
    'X-User-ID' => '***************',
    'Content-Type' => 'application/json'
  ));
  $client->enqueue($request)->send();
  $response = $client->getResponse();
  echo $response->getBody();

Fetch Voices API

Overview of API

There are two endpoints on the API that you will use to convert text to speech:

1. /getVoices: this endpoint fetches all voices for standard and Ultra- Realistic Voices (takes a query params ultra=true for ultra realistic voices)

Convert text to speech

• Endpoint: ./getVoices?ultra={true/false}

Use this endpoint to Fetch all available voices.

- Method: GET

• Response (JSON):

  {
    "voices": [],
  }

• Examples (cURL Request):

  curl --location --request GET 'https://play.ht/api/v1/getVoices?ultra=false' \
  --header 'Authorization: **************' \
  --header 'X-User-ID: ***************' \
  --header 'Content-Type: application/json' \

Errors

Play.ht API uses the following error codes:

Standard API Voices

This is a list of all the available text to speech voices in the API with their audio samples.

Use Voice ID and Narration Styles (for supported voices) from this list to reference a voice and a narration style, respectively, in your calls to the API. You can also listen to a sample of each voice through its Sample URL.

Utra-Realistic Voices [beta]