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