> ## 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.
# Create Speech
> Convert text to speech with our top-of-the-line PlayAI models.
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](/api-reference/text-to-speech/endpoints/v1/get-async) endpoint with the job ID.
## OpenAPI
````yaml POST /api/v1/tts
openapi: 3.1.0
info:
title: PlayAI API
version: 1.0.0
description: |
A single, combined OpenAPI specification that merges:
• PlayAI Agent API
• PlayAI PlayNote API
• PlayAI Text-to-Speech (TTS) API
• PlayAI Dialog Turbo API
This file contains all endpoints, schemas, and components
from the four original specs. See "Merged Issues" below
for notes on how certain conflicts were resolved.
servers:
- url: https://api.play.ai
security:
- ApiKeyAuth: []
XUserIdAuth: []
paths:
/api/v1/tts:
post:
requestBody:
content:
application/json:
schema:
title: Generate speech with PlayAI models
type: object
properties:
model:
type: string
enum:
- PlayDialog
- Play3.0-mini
example: PlayDialog
default: PlayDialog
nullable: false
description: >-
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](/api-reference/text-to-speech/endpoints/v1/stream-speech-turbo).
>**💡 Tip:** For more information, see
[Models](/documentation/text-to-speech/tts-models).
text:
type: string
description: >-
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:
$ref: '#/components/schemas/VoiceId'
description: >-
The unique ID for a voice to be used.
>**💡 Tip:** Check out the [How to Get ID of
Voices](/documentation/text-to-speech/tts-voices#how-to-use-a-voice)
guide
voice2:
$ref: '#/components/schemas/VoiceId'
nullable: true
description: >
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](/documentation/text-to-speech/tts-voices#how-to-use-a-voice)
guide
turnPrefix:
type: string
nullable: true
example: 'Country Mouse:'
turnPrefix2:
type: string
nullable: true
example: 'Town Mouse:'
quality:
type: string
enum:
- draft
- low
- medium
- high
- premium
description: Only supported with `Play3.0-mini`.
outputFormat:
type: string
enum:
- mp3
- mulaw
- raw
- wav
- ogg
- flac
default: mp3
nullable: true
speed:
type: number
example: 1
minimum: 0.1
maximum: 5
sampleRate:
type: number
example: 24000
minimum: 8000
maximum: 48000
seed:
type: number
nullable: true
example: null
minimum: 0
temperature:
type: number
nullable: true
example: null
minimum: 0
maximum: 2
voiceGuidance:
type: number
minimum: 1
maximum: 6
nullable: true
example: null
description: Only for `Play3.0-mini`.
styleGuidance:
type: number
minimum: 1
maximum: 30
example: null
nullable: true
textGuidance:
type: number
minimum: 1
maximum: 2
example: 1
nullable: true
prompt:
type: string
nullable: true
prompt2:
type: string
nullable: true
voiceConditioningSeconds:
type: number
nullable: true
default: 20
voiceConditioningSeconds2:
type: number
nullable: true
default: 20
language:
oneOf:
- type: string
enum:
- 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
default: english
webHookUrl:
type: string
format: uri
nullable: true
required:
- model
- text
- voice
responses:
'201':
description: The TTS job created.
content:
application/json:
schema:
$ref: '#/components/schemas/TtsAsyncJob'
'400':
$ref: '#/components/responses/400-InvalidParametersError'
'401':
$ref: '#/components/responses/401-UnauthorizedError'
'403':
$ref: '#/components/responses/403-ForbiddenError'
'429':
$ref: '#/components/responses/429-RateLimitedError'
'500':
$ref: '#/components/responses/500-UnexpectedError'
components:
schemas:
VoiceId:
description: The unique ID for a PlayAI Voice.
type: string
example: >-
s3://voice-cloning-zero-shot/baf1ef41-36b6-428c-9bdf-50ba54682bd8/original/manifest.json
TtsAsyncJob:
type: object
required:
- id
- createdAt
- input
- completedAt
- output
properties:
id:
type: string
format: uuid
createdAt:
type: string
format: date-time
input:
type: object
description: The parameters used to create the job.
completedAt:
type: string
format: date-time
nullable: true
output:
oneOf:
- type: object
title: Job completed
required:
- status
- url
- contentType
- fileSize
- duration
properties:
status:
type: string
enum:
- COMPLETED
url:
type: string
format: uri
contentType:
type: string
fileSize:
type: number
duration:
type: number
- type: object
title: Job in progress
required:
- status
properties:
status:
type: string
enum:
- IN_PROGRESS
- type: object
title: Job failed
required:
- status
properties:
status:
type: string
enum:
- FAILED
ErrorResponseObject:
type: object
properties:
errorMessage:
type: string
errorId:
type: string
responses:
400-InvalidParametersError:
description: The provided payload contains one or more invalid parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseObject'
example:
errorMessage: The 'text' parameter must be provided.
errorId: INVALID_PARAMETERS
401-UnauthorizedError:
description: >-
The request was not authorized. Please verify your authorization
headers.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseObject'
example:
errorMessage: >
The authorization header must be provided in the format 'Bearer
'
errorId: UNAUTHORIZED
403-ForbiddenError:
description: >-
The provided API key's plan does not have access to the requested
resource.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseObject'
example:
errorMessage: API access is not available on your current plan.
errorId: UNSUPPORTED_PLAN
429-RateLimitedError:
description: >-
The server has received too many requests from your IP address within a
certain time frame and has temporarily blocked your access to this
resource.
content:
application/json:
schema:
type: string
example: Rate limit exceeded. Please wait a few moments and try again.
500-UnexpectedError:
description: An unexpected error occurred.
content:
application/json:
schema:
type: object
properties:
errorMessage:
type: string
errorId:
type: string
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: >
Your secret API key from [PlayAI](https://play.ai/api/keys), formatted
as `Bearer YOUR_SECRET_API_KEY`.
XUserIdAuth:
type: apiKey
in: header
name: X-USER-ID
description: |
Your unique user ID from [PlayAI](https://play.ai/api/keys).
x-prompt: What is your PlayAI user ID?
````