Skip to main content
POST
/
api
/
v1
/
tts
cURL
curl --request POST \
  --url https://api.play.ai/api/v1/tts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-USER-ID: <api-key>' \
  --data '{
  "model": "PlayDialog",
  "text": "Country Mouse: Welcome to my humble home, cousin! Town Mouse: Thank you, cousin. It'\''s quite... peaceful here. Country Mouse: It is indeed. I hope you'\''re hungry. I'\''ve prepared a simple meal of beans, barley, and fresh roots. Town Mouse: Well, it'\''s... earthy. Do you eat this every day?",
  "voice": "s3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json"
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "createdAt": "2023-11-07T05:31:56Z",
  "input": {},
  "completedAt": "2023-11-07T05:31:56Z",
  "output": {
    "status": "COMPLETED",
    "url": "<string>",
    "contentType": "<string>",
    "fileSize": 123,
    "duration": 123
  }
}
This endpoint does not return the audio output directly. Instead, it returns a job ID that you can use to check the status of your text-to-speech request. To get the status and final audio URL, you’ll need to make an additional call in Get Async Status endpoint with the job ID.

Authorizations

​
Authorization
string
header
required

Your secret API key from PlayAI, formatted as Bearer YOUR_SECRET_API_KEY.

​
X-USER-ID
string
header
required

Your unique user ID from PlayAI.

Body

application/json
​
model
enum<string>
default:PlayDialog
required

The voice engine used to synthesize the voice. Must be either Play3.0-mini or PlayDialog.

  • Dialog 1.0: Our flagship model with best quality and multi-turn dialogue capabilities.
  • Play 3.0 Mini: Our fast and efficient model for single-voice text-to-speech.

ℹ️ NOTE: We also offer Dialog 1.0 Turbo which is a faster version of Dialog 1.0 from a separate endpoint.

💡 Tip: For more information, see Models.

Available options:
PlayDialog,
Play3.0-mini
Example:

"PlayDialog"

​
text
string
required

The text to be converted to speech. Limited to 20k characters for Play3.0-mini, 50k characters for PlayDialog.

Example:

"Country Mouse: Welcome to my humble home, cousin! Town Mouse: Thank you, cousin. It's quite... peaceful here. Country Mouse: It is indeed. I hope you're hungry. I've prepared a simple meal of beans, barley, and fresh roots. Town Mouse: Well, it's... earthy. Do you eat this every day?"

​
voice
string
required

The unique ID for a voice to be used.

💡 Tip: Check out the How to Get ID of Voices guide

Example:

"s3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json"

​
voice2
string

The unique ID for a second PlayAI Voice. Used for multi-turn dialogues only in PlayDialog.

💡 Tip: Check out the How to Get ID of Voices guide

Example:

"s3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json"

​
turnPrefix
string | null
Example:

"Country Mouse:"

​
turnPrefix2
string | null
Example:

"Town Mouse:"

​
quality
enum<string>

Only supported with Play3.0-mini.

Available options:
draft,
low,
medium,
high,
premium
​
outputFormat
enum<string> | null
default:mp3
Available options:
mp3,
mulaw,
raw,
wav,
ogg,
flac
​
speed
number
Required range: 0.1 <= x <= 5
Example:

1

​
sampleRate
number
Required range: 8000 <= x <= 48000
Example:

24000

​
seed
number | null
Required range: x >= 0
Example:

null

​
temperature
number | null
Required range: 0 <= x <= 2
Example:

null

​
voiceGuidance
number | null

Only for Play3.0-mini.

Required range: 1 <= x <= 6
Example:

null

​
styleGuidance
number | null
Required range: 1 <= x <= 30
Example:

null

​
textGuidance
number | null
Required range: 1 <= x <= 2
Example:

1

​
prompt
string | null
​
prompt2
string | null
​
voiceConditioningSeconds
number | null
default:20
​
voiceConditioningSeconds2
number | null
default:20
​
language
enum<string>
default:english
Available options:
afrikaans,
albanian,
amharic,
arabic,
bengali,
bulgarian,
catalan,
croatian,
czech,
danish,
dutch,
english,
french,
galician,
german,
greek,
hebrew,
hindi,
hungarian,
indonesian,
italian,
japanese,
korean,
malay,
mandarin,
polish,
portuguese,
russian,
serbian,
spanish,
swedish,
tagalog,
thai,
turkish,
ukrainian,
urdu,
xhosa
​
webHookUrl
string<uri> | null

Response

The TTS job created.

​
id
string<uuid>
required
​
createdAt
string<date-time>
required
​
input
object
required

The parameters used to create the job.

​
completedAt
string<date-time> | null
required
​
output
object
required
  • Job completed
  • Job in progress
  • Job failed