Ultra Realistic Voices API

Convert text to speech

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

This endpoint trigger text to speech conversion.

• Endpoint: https://play.ht/api/v1/convert
• Method: POST
• Content-Type: application/json
• Headers - get it from Dashboard :
  • Authorization: This is where your secret key goes.
  • X-User-ID: This is where your Play.ht user ID goes

Request Body (JSON):

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

How the request body looks like
{
  "voice": string,
  "content": string[],
  "title": string, // Optional
  "speed": string, // Optional
  "preset": string // Optional
}

• voice is the id of the voice used to synthesize the text. Refer to the Voices reference file 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. optional

• preset this controls the quality of the output audio, 'real-time', ‘balanced’, ‘low-latency’, 'high-quality'. optional

Receiving the audio file

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

 Status polling response
{
  "status": "CREATED",
  "transcriptionId": "0f7ed3c9-8595-4739-b117-d94128688b20",
  "contentLength": 4,
  "wordCount": 4
}

Status polling :

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

• Endpoint: https://play.ht/api/v1/articleStatus
• Method: GET
• URL Parameters: transcriptionId (required)
• Content-Type: application/json
• Headers - get it from Dashboard :
  • Authorization: This is where your secret key goes.
  • X-User-ID: This is where your Play.ht user ID goes

  Webhook request body (when the conversion is complete)
{
  "status": "SUCCESS",
  "voice": "william",
  "transcriptionId": "0f7ed3c9-8595-4739-b117-d94128688b20",
  "metadata": {
    "progress": 100,
    "output": [
      "https://peregrine-results.s3.us-east-2.amazonaws.com/results/0f7ed3c9-8595-4739-b117-d94128688b20_0.wav"
    ]
  }
}

Use a webhook (recommended):

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

• Add your webhook URL from the dashboard Register Webhook.
• The webhook will be called with the conversion status and the S3 URL to download the audio file.

Streaming

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

Our v2 API supports streaming. Please see the Streaming section of our new docs for more details.

Voices

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

 How voices looks like
{
  "name": "William",
  "gender": "male",
  "value": "william",
  "accent": "american",
  "age": "adult",
  "tempo": "neutral",
  "loudness": "neutral",
  "language": "English (US)",
  "languageCode": "EN-US",
  "sample": "https://peregrine-samples.s3.amazonaws.com/editor-samples/william_vo.wav",
  "texture": "round",
  "style": "videos",
  "hq": true,
  "isPopular": true,
  "isNew": false,
  "isExperimental": false
}

• Endpoint: https://play.ht/api/v1/getVoices?ultra=true
• Method: GET
• Content-Type: application/json

• Headers - get it from Dashboard :

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

• choose a voice from the list and use the voice value as the voice parameter in the convert endpoint , for example: william.

Cloned voices

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

How clonnd voices looks like
{
  "id": "s3://mockingbird-prod/william_3_d2b62fd7-a52d-4bd1-a09a-fb2748eda979/voices/william_3/manifest.json",
  "name": "William 3",
  "value": "s3://mockingbird-prod/william_3_d2b62fd7-a52d-4bd1-a09a-fb2748eda979/voices/william_3/manifest.json",
  "isCloned": true,
  "gender": null
}

• Endpoint: https://play.ht/api/v1/getClonedVoices
• Method: GET
• Content-Type: application/json

• Headers - get it from Dashboard :

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

• if you have cloned a voice, you will find it in the list and you can use it as well by using the value as the voice parameter in the convert endpoint , for example: s3://mockingbird-prod/william_3_d2b62fd7-a52d-4bd1-a09a-fb2748eda979/voices/william_3/manifest.json.

Utra-Realistic Voices

• Access the full list of voices from the getVoices endpoint.

Standard & Premium Voices API

Convert text to speech (S&P)

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

This endpoint trigger text to speech conversion.

• Endpoint: https://play.ht/api/v1/convert
• Method: POST
• Content-Type: application/json
• Headers - get it from Dashboard :
  • Authorization: This is where your secret key goes.
  • X-User-ID: This is where your Play.ht user ID goes

Request Body (JSON):

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

How the request body looks like
{
    "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
}

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"
}'

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)

<?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();

• 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):

   Convertion response
  {
    "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.

Receiving the audio file (S&P)

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

 Status polling response
{
  "status": "CREATED",
  "transcriptionId": "-NOjGbpFU1Exf3DxhLHU",
  "contentLength": 1,
  "wordCount": 4
}

Status polling :

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

• Endpoint: https://play.ht/api/v1/articleStatus
• Method: GET
• URL Parameters: transcriptionId (required)
• Content-Type: application/json
• Headers - get it from Dashboard :
  • Authorization: This is where your secret key goes.
  • X-User-ID: This is where your Play.ht user ID goes

 Webhook request body (when the conversion is complete)
{
  "status": "SUCCESS",
  "voice": "Matthew",
  "transcriptionId": "-NOjGbpFU1Exf3DxhLHU",
  "metadata": {
    "progress": 100,
    "output": [
      "https://media.play.ht/full_-NOjGbpFU1Exf3DxhLHU.mp3?generation=1676904136913200&alt=media"
    ],
    "duration": 2.208,
    "size": 13507
  }
}

Use a webhook (recommended):

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

• Add your webhook URL from the dashboard Register Webhook.
• The webhook will be called with the conversion status and the S3 URL to download the audio file.

Streaming

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

Streaming is only supported on Ultra-Realistic voices. Please see the Streaming section of our new docs for more details.

Voices (S&P)

💡 This page is now archived for historic purposes. If you're looking for the most up-to-date information and documentation, please visit our new docs: https://docs.play.ht

 How voices looks like
{
  "value": "Matthew",
  "name": "Matthew",
  "language": "English (US)",
  "voiceType": "Standard",
  "languageCode": "en-US",
  "gender": "Male",
  "service": "polly",
  "sample": "https://firebasestorage.googleapis.com/v0/b/play-68705.appspot.com/o/0-sample-mathew-speech_20171218030814983.mp3?alt=media&token=63ec628e-aeed-4f9b-b6ba-0d684f9d033e"
}

• Endpoint: https://play.ht/api/v1/getVoices
• Method: GET
• Content-Type: application/json

• Headers - get it from Dashboard :

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

• choose a voice from the list and use the voice value as the voice parameter in the convert endpoint , for example: Matthew.

Standard API Voices

• Access the full list of voices from the getVoices endpoint.

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.