2026/11/19 - Amazon Polly - 3 new 2 updated api methods
Changes Adds voice cloning to Amazon Polly. The new CreateVoice, GetVoice and DeleteVoice operations create and manage a custom voice from a speaker's recording, usable with the generative engine in all synthesis operations.
Deletes a custom voice. DescribeVoices and GetVoice stop returning the voice immediately. You can't restore a deleted voice.
You can delete a voice in active or failed status. If the voice is in pending status, the request fails with ConflictException. If no custom voice with the specified ID exists in your account and Region, the request fails with ResourceNotFoundException. You can delete the voice even if you disabled its Amazon Web Services KMS key or scheduled it for deletion.
This operation requires permissions to perform the polly:DeleteVoice action.
See also: AWS API Documentation
Request Syntax
client.delete_voice(
VoiceId='string'
)
string
[REQUIRED]
The ID of the custom voice to delete, for example, vc-9a8fa85dd3. You can't specify the ARN of the voice.
dict
Response Syntax
{}
Response Structure
(dict) --
Creates a custom voice from recordings of a speaker and returns it in pending status. Use GetVoice to check the status. When the status is active, you can use the voice ID in SynthesizeSpeech, StartSpeechSynthesisTask, and StartSpeechSynthesisStream.
The custom-voice-max-count service quota limits the number of custom voices in your account in each Region. If you reach the quota, the request fails with ServiceQuotaExceededException.
This operation requires permissions to perform the polly:CreateVoice action. You also need s3:GetObject permission on each recording that you specify by S3Url. If you specify a customer managed key, you also need kms:DescribeKey, kms:GenerateDataKey, and kms:Decrypt permissions on the key. If you specify Tags, you also need the polly:TagResource permission.
See also: AWS API Documentation
Request Syntax
client.create_voice(
Name='string',
LanguageCode='de-DE'|'en-US'|'es-US'|'fr-FR'|'hi-IN'|'it-IT'|'pt-BR',
TermsAccepted=True|False,
VoiceCreationData={
'Recordings': [
{
'Format': 'wav'|'flac'|'ogg_vorbis'|'mp3',
'Data': {
'S3Url': 'string',
'Bytes': b'bytes'
}
},
]
},
CustomerManagedEncryption={
'KmsKeyArn': 'string',
'EncryptionContext': {
'string': 'string'
}
},
Tags={
'string': 'string'
},
ClientToken='string'
)
string
[REQUIRED]
The name of the voice. Use the name to identify the voice in your application. The name can contain letters, digits, hyphens, and underscores, and can be up to 64 characters long. The name doesn't have to be unique. The name isn't the voice ID, which Amazon Polly assigns.
string
[REQUIRED]
The language of the recordings, for example, en-US. Amazon Polly doesn't detect the language from the recordings.
boolean
[REQUIRED]
Confirms the following two statements:
"I confirm that I have obtained all necessary consents required under any applicable laws and regulations, including biometric privacy laws, from the owner of this voice to clone these voice samples."
"I confirm that I will not use the generated content for any illegal, fraudulent, or harmful purpose and reaffirm my obligation to abide by the AWS Service Terms, Biometric Notice and Consent Terms, AWS Responsible AI Policy, and AWS Acceptable Use Policy."
You can read the AWS Service Terms, the Biometric Notice and Consent Terms, the AWS Responsible AI Policy, and the AWS Acceptable Use Policy on the Amazon Web Services website.
You must set this parameter to true to create a voice. Otherwise, the request fails with ValidationException.
dict
[REQUIRED]
The recordings that Amazon Polly uses to create the voice.
Recordings (list) -- [REQUIRED]
The recordings of the speaker. Each recording specifies its audio format and its audio source.
(dict) --
A recording of the speaker whose voice you want to create. The recording specifies its audio format and its audio source.
Format (string) -- [REQUIRED]
The audio format of the recording: wav, flac, ogg_vorbis, or mp3. The format must match the audio data.
Data (dict) -- [REQUIRED]
The audio source of the recording. Specify either an Amazon S3 object or the audio data.
S3Url (string) --
The Amazon S3 URL of the audio object, in the form s3://bucket/key. You need s3:GetObject permission on the object.
Bytes (bytes) --
The audio data, passed directly in the request. The data must be in the format that Format specifies and can be up to 5 MB. Amazon Polly doesn't store the audio after it creates the voice, and doesn't return this field in responses.
dict
The customer managed key that you want Amazon Polly to encrypt the voice with. If you omit this parameter, Amazon Polly encrypts the voice with an Amazon Web Services owned key.
KmsKeyArn (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the key. The key must be a symmetric encryption key in the same Amazon Web Services Region as the voice. To create the voice, you need kms:DescribeKey, kms:GenerateDataKey, and kms:Decrypt permissions on the key. To synthesize speech with the voice, you need kms:Decrypt permission on the key.
EncryptionContext (dict) --
The key-value pairs that Amazon Polly includes as the encryption context when it encrypts or decrypts the voice with the key. You can use these pairs in key policy conditions. Don't use keys that start with aws:, which are reserved.
(string) --
(string) --
dict
The tags that you apply to the voice to help you categorize and organize it. Each tag consists of a key and an optional value, both of which you define.
(string) --
(string) --
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If you don't specify a client token, the Amazon Web Services SDKs generate one for you. If you retry a request that succeeded with the same client token and the same parameters, Amazon Polly returns the voice that the first request created and doesn't create a second voice.
This field is autopopulated if not provided.
dict
Response Syntax
{
'Voice': {
'Arn': 'string',
'Gender': 'Female'|'Male',
'Id': 'Aditi'|'Amy'|'Astrid'|'Bianca'|'Brian'|'Camila'|'Carla'|'Carmen'|'Celine'|'Chantal'|'Conchita'|'Cristiano'|'Dora'|'Emma'|'Enrique'|'Ewa'|'Filiz'|'Gabrielle'|'Geraint'|'Giorgio'|'Gwyneth'|'Hans'|'Ines'|'Ivy'|'Jacek'|'Jan'|'Joanna'|'Joey'|'Justin'|'Karl'|'Kendra'|'Kevin'|'Kimberly'|'Lea'|'Liv'|'Lotte'|'Lucia'|'Lupe'|'Mads'|'Maja'|'Marlene'|'Mathieu'|'Matthew'|'Maxim'|'Mia'|'Miguel'|'Mizuki'|'Naja'|'Nicole'|'Olivia'|'Penelope'|'Raveena'|'Ricardo'|'Ruben'|'Russell'|'Salli'|'Seoyeon'|'Takumi'|'Tatyana'|'Vicki'|'Vitoria'|'Zeina'|'Zhiyu'|'Aria'|'Ayanda'|'Arlet'|'Hannah'|'Arthur'|'Daniel'|'Liam'|'Pedro'|'Kajal'|'Hiujin'|'Laura'|'Elin'|'Ida'|'Suvi'|'Ola'|'Hala'|'Andres'|'Sergio'|'Remi'|'Adriano'|'Thiago'|'Ruth'|'Stephen'|'Kazuha'|'Tomoko'|'Niamh'|'Sofie'|'Lisa'|'Isabelle'|'Zayd'|'Danielle'|'Gregory'|'Burcu'|'Jitka'|'Sabrina'|'Jasmine'|'Jihye'|'Ambre'|'Beatrice'|'Florian'|'Lennart'|'Lorenzo'|'Tiffany'|'Arjun'|'Carlos'|'Carolina'|'Curtis'|'Hyunduk'|'Kenneth'|'Kiara'|'Leo'|'Nate'|'Tina',
'LanguageCode': 'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
'LanguageName': 'string',
'Name': 'string',
'Origin': 'aws'|'customer',
'Status': 'pending'|'active'|'failed',
'StatusReason': 'string',
'AdditionalLanguageCodes': [
'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
],
'SupportedEngines': [
'standard'|'neural'|'long-form'|'generative',
],
'VoiceCreationData': {
'Recordings': [
{
'Format': 'wav'|'flac'|'ogg_vorbis'|'mp3',
'Data': {
'S3Url': 'string',
'Bytes': b'bytes'
}
},
]
},
'CustomerManagedEncryption': {
'KmsKeyArn': 'string',
'EncryptionContext': {
'string': 'string'
}
},
'CreationTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Voice (dict) --
The new voice, in pending status.
Arn (string) --
The Amazon Resource Name (ARN) of a custom voice, in the form arn:partition:polly:region:account-id:voice/voice-id. CreateVoice and GetVoice return this field. Voices that Amazon Polly provides don't have an ARN.
Gender (string) --
The gender of the voice. Custom voices don't include this field.
Id (string) --
The voice ID that Amazon Polly assigns. You specify this ID when you call the SynthesizeSpeech operation. For a custom voice, Amazon Polly assigns an ID that consists of vc- followed by hexadecimal characters, for example, vc-9a8fa85dd3.
LanguageCode (string) --
Language code of the voice.
LanguageName (string) --
Human readable name of the language in English.
Name (string) --
The name of the voice, for example, Salli or Kendra. The name is human-readable, and you might display it in your application. For a custom voice, this is the Name that you specified in CreateVoice.
Origin (string) --
Indicates who provides the voice. The origin is one of the following:
aws
A voice that Amazon Polly provides.
customer
A custom voice that you created with CreateVoice.
Status (string) --
The status of a custom voice. Voices that Amazon Polly provides don't include this field. The status is one of the following:
pending
Amazon Polly is creating the voice.
active
The voice is ready for speech synthesis.
failed
Amazon Polly couldn't create the voice. StatusReason describes why.
StatusReason (string) --
Additional information about the status of a custom voice. When the status is failed, this field describes why Amazon Polly couldn't create the voice.
AdditionalLanguageCodes (list) --
Additional codes for languages available for the specified voice in addition to its default language.
For example, the default language for Aditi is Indian English (en-IN) because it was first used for that language. Since Aditi is bilingual and fluent in both Indian English and Hindi, this parameter would show the code hi-IN.
(string) --
SupportedEngines (list) --
Specifies which engines ( standard, neural, long-form or generative) are supported by a given voice.
(string) --
VoiceCreationData (dict) --
The data from which you created the custom voice. CreateVoice and GetVoice return this field. The response doesn't include the audio: a recording that Amazon Polly read from Amazon S3 includes its S3Url, and a recording that you passed as Bytes has no fields in Data.
Recordings (list) --
The recordings of the speaker. Each recording specifies its audio format and its audio source.
(dict) --
A recording of the speaker whose voice you want to create. The recording specifies its audio format and its audio source.
Format (string) --
The audio format of the recording: wav, flac, ogg_vorbis, or mp3. The format must match the audio data.
Data (dict) --
The audio source of the recording. Specify either an Amazon S3 object or the audio data.
S3Url (string) --
The Amazon S3 URL of the audio object, in the form s3://bucket/key. You need s3:GetObject permission on the object.
Bytes (bytes) --
The audio data, passed directly in the request. The data must be in the format that Format specifies and can be up to 5 MB. Amazon Polly doesn't store the audio after it creates the voice, and doesn't return this field in responses.
CustomerManagedEncryption (dict) --
The customer managed key that encrypts your custom voice. CreateVoice and GetVoice return this field if you specified a key in CreateVoice.
KmsKeyArn (string) --
The Amazon Resource Name (ARN) of the key. The key must be a symmetric encryption key in the same Amazon Web Services Region as the voice. To create the voice, you need kms:DescribeKey, kms:GenerateDataKey, and kms:Decrypt permissions on the key. To synthesize speech with the voice, you need kms:Decrypt permission on the key.
EncryptionContext (dict) --
The key-value pairs that Amazon Polly includes as the encryption context when it encrypts or decrypts the voice with the key. You can use these pairs in key policy conditions. Don't use keys that start with aws:, which are reserved.
(string) --
(string) --
CreationTime (datetime) --
The date and time when you created the custom voice. Voices that Amazon Polly provides don't include this field.
Returns the status and properties of a custom voice. Use this operation after CreateVoice to check whether the status of the voice is active or failed. Unlike DescribeVoices, GetVoice also returns Arn, VoiceCreationData, CustomerManagedEncryption, and StatusReason. If no custom voice with the specified ID exists in your account and Region, the request fails with ResourceNotFoundException.
This operation requires permissions to perform the polly:GetVoice action.
See also: AWS API Documentation
Request Syntax
client.get_voice(
VoiceId='string'
)
string
[REQUIRED]
The ID of the custom voice that CreateVoice returned, for example, vc-9a8fa85dd3. You can't specify the ARN of the voice.
dict
Response Syntax
{
'Voice': {
'Arn': 'string',
'Gender': 'Female'|'Male',
'Id': 'Aditi'|'Amy'|'Astrid'|'Bianca'|'Brian'|'Camila'|'Carla'|'Carmen'|'Celine'|'Chantal'|'Conchita'|'Cristiano'|'Dora'|'Emma'|'Enrique'|'Ewa'|'Filiz'|'Gabrielle'|'Geraint'|'Giorgio'|'Gwyneth'|'Hans'|'Ines'|'Ivy'|'Jacek'|'Jan'|'Joanna'|'Joey'|'Justin'|'Karl'|'Kendra'|'Kevin'|'Kimberly'|'Lea'|'Liv'|'Lotte'|'Lucia'|'Lupe'|'Mads'|'Maja'|'Marlene'|'Mathieu'|'Matthew'|'Maxim'|'Mia'|'Miguel'|'Mizuki'|'Naja'|'Nicole'|'Olivia'|'Penelope'|'Raveena'|'Ricardo'|'Ruben'|'Russell'|'Salli'|'Seoyeon'|'Takumi'|'Tatyana'|'Vicki'|'Vitoria'|'Zeina'|'Zhiyu'|'Aria'|'Ayanda'|'Arlet'|'Hannah'|'Arthur'|'Daniel'|'Liam'|'Pedro'|'Kajal'|'Hiujin'|'Laura'|'Elin'|'Ida'|'Suvi'|'Ola'|'Hala'|'Andres'|'Sergio'|'Remi'|'Adriano'|'Thiago'|'Ruth'|'Stephen'|'Kazuha'|'Tomoko'|'Niamh'|'Sofie'|'Lisa'|'Isabelle'|'Zayd'|'Danielle'|'Gregory'|'Burcu'|'Jitka'|'Sabrina'|'Jasmine'|'Jihye'|'Ambre'|'Beatrice'|'Florian'|'Lennart'|'Lorenzo'|'Tiffany'|'Arjun'|'Carlos'|'Carolina'|'Curtis'|'Hyunduk'|'Kenneth'|'Kiara'|'Leo'|'Nate'|'Tina',
'LanguageCode': 'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
'LanguageName': 'string',
'Name': 'string',
'Origin': 'aws'|'customer',
'Status': 'pending'|'active'|'failed',
'StatusReason': 'string',
'AdditionalLanguageCodes': [
'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
],
'SupportedEngines': [
'standard'|'neural'|'long-form'|'generative',
],
'VoiceCreationData': {
'Recordings': [
{
'Format': 'wav'|'flac'|'ogg_vorbis'|'mp3',
'Data': {
'S3Url': 'string',
'Bytes': b'bytes'
}
},
]
},
'CustomerManagedEncryption': {
'KmsKeyArn': 'string',
'EncryptionContext': {
'string': 'string'
}
},
'CreationTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Voice (dict) --
The custom voice.
Arn (string) --
The Amazon Resource Name (ARN) of a custom voice, in the form arn:partition:polly:region:account-id:voice/voice-id. CreateVoice and GetVoice return this field. Voices that Amazon Polly provides don't have an ARN.
Gender (string) --
The gender of the voice. Custom voices don't include this field.
Id (string) --
The voice ID that Amazon Polly assigns. You specify this ID when you call the SynthesizeSpeech operation. For a custom voice, Amazon Polly assigns an ID that consists of vc- followed by hexadecimal characters, for example, vc-9a8fa85dd3.
LanguageCode (string) --
Language code of the voice.
LanguageName (string) --
Human readable name of the language in English.
Name (string) --
The name of the voice, for example, Salli or Kendra. The name is human-readable, and you might display it in your application. For a custom voice, this is the Name that you specified in CreateVoice.
Origin (string) --
Indicates who provides the voice. The origin is one of the following:
aws
A voice that Amazon Polly provides.
customer
A custom voice that you created with CreateVoice.
Status (string) --
The status of a custom voice. Voices that Amazon Polly provides don't include this field. The status is one of the following:
pending
Amazon Polly is creating the voice.
active
The voice is ready for speech synthesis.
failed
Amazon Polly couldn't create the voice. StatusReason describes why.
StatusReason (string) --
Additional information about the status of a custom voice. When the status is failed, this field describes why Amazon Polly couldn't create the voice.
AdditionalLanguageCodes (list) --
Additional codes for languages available for the specified voice in addition to its default language.
For example, the default language for Aditi is Indian English (en-IN) because it was first used for that language. Since Aditi is bilingual and fluent in both Indian English and Hindi, this parameter would show the code hi-IN.
(string) --
SupportedEngines (list) --
Specifies which engines ( standard, neural, long-form or generative) are supported by a given voice.
(string) --
VoiceCreationData (dict) --
The data from which you created the custom voice. CreateVoice and GetVoice return this field. The response doesn't include the audio: a recording that Amazon Polly read from Amazon S3 includes its S3Url, and a recording that you passed as Bytes has no fields in Data.
Recordings (list) --
The recordings of the speaker. Each recording specifies its audio format and its audio source.
(dict) --
A recording of the speaker whose voice you want to create. The recording specifies its audio format and its audio source.
Format (string) --
The audio format of the recording: wav, flac, ogg_vorbis, or mp3. The format must match the audio data.
Data (dict) --
The audio source of the recording. Specify either an Amazon S3 object or the audio data.
S3Url (string) --
The Amazon S3 URL of the audio object, in the form s3://bucket/key. You need s3:GetObject permission on the object.
Bytes (bytes) --
The audio data, passed directly in the request. The data must be in the format that Format specifies and can be up to 5 MB. Amazon Polly doesn't store the audio after it creates the voice, and doesn't return this field in responses.
CustomerManagedEncryption (dict) --
The customer managed key that encrypts your custom voice. CreateVoice and GetVoice return this field if you specified a key in CreateVoice.
KmsKeyArn (string) --
The Amazon Resource Name (ARN) of the key. The key must be a symmetric encryption key in the same Amazon Web Services Region as the voice. To create the voice, you need kms:DescribeKey, kms:GenerateDataKey, and kms:Decrypt permissions on the key. To synthesize speech with the voice, you need kms:Decrypt permission on the key.
EncryptionContext (dict) --
The key-value pairs that Amazon Polly includes as the encryption context when it encrypts or decrypts the voice with the key. You can use these pairs in key policy conditions. Don't use keys that start with aws:, which are reserved.
(string) --
(string) --
CreationTime (datetime) --
The date and time when you created the custom voice. Voices that Amazon Polly provides don't include this field.
{'Voices': {'Arn': 'string',
'CreationTime': 'timestamp',
'CustomerManagedEncryption': {'EncryptionContext': {'string': 'string'},
'KmsKeyArn': 'string'},
'Origin': 'aws | customer',
'Status': 'pending | active | failed',
'StatusReason': 'string',
'VoiceCreationData': {'Recordings': [{'Data': {'Bytes': 'blob',
'S3Url': 'string'},
'Format': 'wav | flac | '
'ogg_vorbis | '
'mp3'}]}}}
Returns the list of voices: the voices that Amazon Polly provides and the custom voices in your account. Each voice speaks a specified language and is identified by an ID. A voice that Amazon Polly provides is either male or female, and its ID is the ASCII version of the voice name.
When synthesizing speech ( SynthesizeSpeech), you provide the voice ID for the voice you want from the list of voices returned by DescribeVoices.
For example, your news reader application reads news in a specific language, and you want to give users the option to choose the voice. With the DescribeVoices operation, you can provide a list of available voices for users to choose from.
You can optionally specify a language code to filter the available voices. For example, if you specify en-US, the operation returns a list of all available US English voices.
The list includes custom voices in every status. For each voice, Origin indicates whether Amazon Polly provides the voice or you created it. You can use a custom voice for synthesis only when its status is active. A voice in failed status stays in the list until you delete it.
For a custom voice, DescribeVoices returns Origin, Id, Name, Status, LanguageCode, LanguageName, SupportedEngines, and CreationTime. To get Arn, StatusReason, VoiceCreationData, and CustomerManagedEncryption, use GetVoice.
The LanguageCode and Engine filters apply to custom voices in the same way as to voices that Amazon Polly provides.
This operation requires permissions to perform the polly:DescribeVoices action.
See also: AWS API Documentation
Request Syntax
client.describe_voices(
Engine='standard'|'neural'|'long-form'|'generative',
LanguageCode='arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
IncludeAdditionalLanguageCodes=True|False,
NextToken='string'
)
string
Specifies the engine ( standard, neural, long-form or generative) used by Amazon Polly when processing input text for speech synthesis.
string
The language identification tag (ISO 639 code for the language name-ISO 3166 country code) for filtering the list of voices returned. If you don't specify this optional parameter, all available voices are returned.
boolean
Boolean value indicating whether to return any bilingual voices that use the specified language as an additional language. For instance, if you request all languages that use US English (es-US), and there is an Italian voice that speaks both Italian (it-IT) and US English, that voice will be included if you specify yes but not if you specify no.
string
An opaque pagination token returned from the previous DescribeVoices operation. If present, this indicates where to continue the listing.
dict
Response Syntax
{
'Voices': [
{
'Arn': 'string',
'Gender': 'Female'|'Male',
'Id': 'Aditi'|'Amy'|'Astrid'|'Bianca'|'Brian'|'Camila'|'Carla'|'Carmen'|'Celine'|'Chantal'|'Conchita'|'Cristiano'|'Dora'|'Emma'|'Enrique'|'Ewa'|'Filiz'|'Gabrielle'|'Geraint'|'Giorgio'|'Gwyneth'|'Hans'|'Ines'|'Ivy'|'Jacek'|'Jan'|'Joanna'|'Joey'|'Justin'|'Karl'|'Kendra'|'Kevin'|'Kimberly'|'Lea'|'Liv'|'Lotte'|'Lucia'|'Lupe'|'Mads'|'Maja'|'Marlene'|'Mathieu'|'Matthew'|'Maxim'|'Mia'|'Miguel'|'Mizuki'|'Naja'|'Nicole'|'Olivia'|'Penelope'|'Raveena'|'Ricardo'|'Ruben'|'Russell'|'Salli'|'Seoyeon'|'Takumi'|'Tatyana'|'Vicki'|'Vitoria'|'Zeina'|'Zhiyu'|'Aria'|'Ayanda'|'Arlet'|'Hannah'|'Arthur'|'Daniel'|'Liam'|'Pedro'|'Kajal'|'Hiujin'|'Laura'|'Elin'|'Ida'|'Suvi'|'Ola'|'Hala'|'Andres'|'Sergio'|'Remi'|'Adriano'|'Thiago'|'Ruth'|'Stephen'|'Kazuha'|'Tomoko'|'Niamh'|'Sofie'|'Lisa'|'Isabelle'|'Zayd'|'Danielle'|'Gregory'|'Burcu'|'Jitka'|'Sabrina'|'Jasmine'|'Jihye'|'Ambre'|'Beatrice'|'Florian'|'Lennart'|'Lorenzo'|'Tiffany'|'Arjun'|'Carlos'|'Carolina'|'Curtis'|'Hyunduk'|'Kenneth'|'Kiara'|'Leo'|'Nate'|'Tina',
'LanguageCode': 'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
'LanguageName': 'string',
'Name': 'string',
'Origin': 'aws'|'customer',
'Status': 'pending'|'active'|'failed',
'StatusReason': 'string',
'AdditionalLanguageCodes': [
'arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
],
'SupportedEngines': [
'standard'|'neural'|'long-form'|'generative',
],
'VoiceCreationData': {
'Recordings': [
{
'Format': 'wav'|'flac'|'ogg_vorbis'|'mp3',
'Data': {
'S3Url': 'string',
'Bytes': b'bytes'
}
},
]
},
'CustomerManagedEncryption': {
'KmsKeyArn': 'string',
'EncryptionContext': {
'string': 'string'
}
},
'CreationTime': datetime(2015, 1, 1)
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
Voices (list) --
A list of voices with their properties.
(dict) --
Describes a voice. Amazon Polly provides voices, and you can create custom voices with CreateVoice. Origin indicates whether Amazon Polly provides the voice or you created it. DescribeVoices returns a subset of the fields for each voice. GetVoice returns all fields of a custom voice.
Arn (string) --
The Amazon Resource Name (ARN) of a custom voice, in the form arn:partition:polly:region:account-id:voice/voice-id. CreateVoice and GetVoice return this field. Voices that Amazon Polly provides don't have an ARN.
Gender (string) --
The gender of the voice. Custom voices don't include this field.
Id (string) --
The voice ID that Amazon Polly assigns. You specify this ID when you call the SynthesizeSpeech operation. For a custom voice, Amazon Polly assigns an ID that consists of vc- followed by hexadecimal characters, for example, vc-9a8fa85dd3.
LanguageCode (string) --
Language code of the voice.
LanguageName (string) --
Human readable name of the language in English.
Name (string) --
The name of the voice, for example, Salli or Kendra. The name is human-readable, and you might display it in your application. For a custom voice, this is the Name that you specified in CreateVoice.
Origin (string) --
Indicates who provides the voice. The origin is one of the following:
aws
A voice that Amazon Polly provides.
customer
A custom voice that you created with CreateVoice.
Status (string) --
The status of a custom voice. Voices that Amazon Polly provides don't include this field. The status is one of the following:
pending
Amazon Polly is creating the voice.
active
The voice is ready for speech synthesis.
failed
Amazon Polly couldn't create the voice. StatusReason describes why.
StatusReason (string) --
Additional information about the status of a custom voice. When the status is failed, this field describes why Amazon Polly couldn't create the voice.
AdditionalLanguageCodes (list) --
Additional codes for languages available for the specified voice in addition to its default language.
For example, the default language for Aditi is Indian English (en-IN) because it was first used for that language. Since Aditi is bilingual and fluent in both Indian English and Hindi, this parameter would show the code hi-IN.
(string) --
SupportedEngines (list) --
Specifies which engines ( standard, neural, long-form or generative) are supported by a given voice.
(string) --
VoiceCreationData (dict) --
The data from which you created the custom voice. CreateVoice and GetVoice return this field. The response doesn't include the audio: a recording that Amazon Polly read from Amazon S3 includes its S3Url, and a recording that you passed as Bytes has no fields in Data.
Recordings (list) --
The recordings of the speaker. Each recording specifies its audio format and its audio source.
(dict) --
A recording of the speaker whose voice you want to create. The recording specifies its audio format and its audio source.
Format (string) --
The audio format of the recording: wav, flac, ogg_vorbis, or mp3. The format must match the audio data.
Data (dict) --
The audio source of the recording. Specify either an Amazon S3 object or the audio data.
S3Url (string) --
The Amazon S3 URL of the audio object, in the form s3://bucket/key. You need s3:GetObject permission on the object.
Bytes (bytes) --
The audio data, passed directly in the request. The data must be in the format that Format specifies and can be up to 5 MB. Amazon Polly doesn't store the audio after it creates the voice, and doesn't return this field in responses.
CustomerManagedEncryption (dict) --
The customer managed key that encrypts your custom voice. CreateVoice and GetVoice return this field if you specified a key in CreateVoice.
KmsKeyArn (string) --
The Amazon Resource Name (ARN) of the key. The key must be a symmetric encryption key in the same Amazon Web Services Region as the voice. To create the voice, you need kms:DescribeKey, kms:GenerateDataKey, and kms:Decrypt permissions on the key. To synthesize speech with the voice, you need kms:Decrypt permission on the key.
EncryptionContext (dict) --
The key-value pairs that Amazon Polly includes as the encryption context when it encrypts or decrypts the voice with the key. You can use these pairs in key policy conditions. Don't use keys that start with aws:, which are reserved.
(string) --
(string) --
CreationTime (datetime) --
The date and time when you created the custom voice. Voices that Amazon Polly provides don't include this field.
NextToken (string) --
The pagination token to use in the next request to continue the listing of voices. NextToken is returned only if the response is truncated.
{'EventStream': {'ServiceQuotaExceededException': {'quotaCode': {'custom-voice-max-count'}},
'ValidationException': {'reason': {'kmsKeyNotFound',
'kmsKeyUnusable'}}}}
Synthesizes UTF-8 input, plain text, or SSML over a bidirectional streaming connection. Specify synthesis parameters in HTTP/2 headers, send text incrementally as events on the input stream, and receive synthesized audio as it becomes available.
This operation serves as a bidirectional counterpart to SynthesizeSpeech:
To use a custom voice, specify its ID in VoiceId. The voice must be in active status. If the voice is in pending or failed status, the request fails with ConflictException. If no custom voice with the specified ID exists in your account and Region, the request fails with ResourceNotFoundException. If the custom voice uses a customer managed key, you need kms:Decrypt permission on the key. If you disabled the key or scheduled it for deletion, the request fails with ValidationException. If you don't have permission to use the key, the request fails with AccessDeniedException. If Amazon Web Services KMS throttles Amazon Polly's request to use the key, the request fails with ThrottlingException.
See also: AWS API Documentation
Request Syntax
client.start_speech_synthesis_stream(
Engine='standard'|'neural'|'long-form'|'generative',
LanguageCode='arb'|'cmn-CN'|'cy-GB'|'da-DK'|'de-DE'|'en-AU'|'en-GB'|'en-GB-WLS'|'en-IN'|'en-US'|'es-ES'|'es-MX'|'es-US'|'fr-CA'|'fr-FR'|'is-IS'|'it-IT'|'ja-JP'|'hi-IN'|'ko-KR'|'nb-NO'|'nl-NL'|'pl-PL'|'pt-BR'|'pt-PT'|'ro-RO'|'ru-RU'|'sv-SE'|'tr-TR'|'en-NZ'|'en-ZA'|'ca-ES'|'de-AT'|'yue-CN'|'ar-AE'|'fi-FI'|'en-IE'|'nl-BE'|'fr-BE'|'cs-CZ'|'de-CH'|'en-SG',
LexiconNames=[
'string',
],
OutputFormat='json'|'mp3'|'ogg_opus'|'ogg_vorbis'|'pcm'|'mulaw'|'alaw',
SampleRate='string',
VoiceId='Aditi'|'Amy'|'Astrid'|'Bianca'|'Brian'|'Camila'|'Carla'|'Carmen'|'Celine'|'Chantal'|'Conchita'|'Cristiano'|'Dora'|'Emma'|'Enrique'|'Ewa'|'Filiz'|'Gabrielle'|'Geraint'|'Giorgio'|'Gwyneth'|'Hans'|'Ines'|'Ivy'|'Jacek'|'Jan'|'Joanna'|'Joey'|'Justin'|'Karl'|'Kendra'|'Kevin'|'Kimberly'|'Lea'|'Liv'|'Lotte'|'Lucia'|'Lupe'|'Mads'|'Maja'|'Marlene'|'Mathieu'|'Matthew'|'Maxim'|'Mia'|'Miguel'|'Mizuki'|'Naja'|'Nicole'|'Olivia'|'Penelope'|'Raveena'|'Ricardo'|'Ruben'|'Russell'|'Salli'|'Seoyeon'|'Takumi'|'Tatyana'|'Vicki'|'Vitoria'|'Zeina'|'Zhiyu'|'Aria'|'Ayanda'|'Arlet'|'Hannah'|'Arthur'|'Daniel'|'Liam'|'Pedro'|'Kajal'|'Hiujin'|'Laura'|'Elin'|'Ida'|'Suvi'|'Ola'|'Hala'|'Andres'|'Sergio'|'Remi'|'Adriano'|'Thiago'|'Ruth'|'Stephen'|'Kazuha'|'Tomoko'|'Niamh'|'Sofie'|'Lisa'|'Isabelle'|'Zayd'|'Danielle'|'Gregory'|'Burcu'|'Jitka'|'Sabrina'|'Jasmine'|'Jihye'|'Ambre'|'Beatrice'|'Florian'|'Lennart'|'Lorenzo'|'Tiffany'|'Arjun'|'Carlos'|'Carolina'|'Curtis'|'Hyunduk'|'Kenneth'|'Kiara'|'Leo'|'Nate'|'Tina',
ActionStream={...}
)
string
[REQUIRED]
Specifies the engine for Amazon Polly to use when processing input text for speech synthesis. Currently, only the generative engine is supported. If you specify a voice that the selected engine doesn't support, Amazon Polly returns an error.
string
An optional parameter that sets the language code for the speech synthesis request. Specify this parameter only when using a bilingual voice. If a bilingual voice is used and no language code is specified, Amazon Polly uses the default language of the bilingual voice.
list
The names of one or more pronunciation lexicons for the service to apply during synthesis. Amazon Polly applies lexicons only when the lexicon language matches the voice language.
(string) --
string
[REQUIRED]
The audio format for the synthesized speech. Currently, Amazon Polly does not support JSON speech marks.
string
The audio frequency, specified in Hz.
string
[REQUIRED]
The voice ID to use for the synthesis. To get a list of available voice IDs, use the DescribeVoices operation. To use a custom voice, specify the voice ID that CreateVoice returned, for example, vc-9a8fa85dd3. You can't specify the ARN of a voice.
dict
The input event stream that contains text events and stream control events.
dict
The response of this operation contains an :class:`.EventStream` member. When iterated the :class:`.EventStream` will yield events based on the structure below, where only one of the top level keys will be present for any given event.
Response Syntax
{
'EventStream': EventStream({
'AudioEvent': {
'AudioChunk': b'bytes'
},
'StreamClosedEvent': {
'RequestCharacters': 123
},
'ValidationException': {
'message': 'string',
'reason': 'unsupportedOperation'|'fieldValidationFailed'|'other'|'invalidInboundEvent'|'kmsKeyNotFound'|'kmsKeyUnusable',
'fields': [
{
'name': 'string',
'message': 'string'
},
]
},
'ServiceQuotaExceededException': {
'message': 'string',
'quotaCode': 'input-stream-inbound-event-timeout'|'input-stream-timeout'|'custom-voice-max-count',
'serviceCode': 'polly'
},
'ServiceFailureException': {
'message': 'string'
},
'ThrottlingException': {
'message': 'string',
'throttlingReasons': [
{
'reason': 'string',
'resource': 'string'
},
]
}
})
}
Response Structure
(dict) --
EventStream (:class:`.EventStream`) --
The output event stream that contains synthesized audio events and stream status events.
AudioEvent (dict) --
An audio event containing synthesized speech.
AudioChunk (bytes) --
A chunk of synthesized audio data encoded in the format specified by the OutputFormat parameter.
StreamClosedEvent (dict) --
An event, with summary information, indicating the stream has closed.
RequestCharacters (integer) --
The total number of characters synthesized during the streaming session.
ValidationException (dict) --
An exception indicating the input failed validation.
message (string) --
reason (string) --
The reason the request failed validation. If Amazon Polly can't use the Amazon Web Services KMS key that you specified in CreateVoice, fields names CustomerManagedEncryption.KmsKeyArn and the reason is one of the following:
kmsKeyNotFound
No key with the specified ARN exists.
kmsKeyUnusable
The key is disabled, scheduled for deletion, or missing its key material, or it isn't a symmetric encryption key.
fields (list) --
The fields that caused the validation error.
(dict) --
Information about a field that failed validation.
name (string) --
The name of the field that failed validation.
message (string) --
A message describing why the field failed validation.
ServiceQuotaExceededException (dict) --
An exception indicating a service quota would be exceeded.
message (string) --
quotaCode (string) --
The quota code identifying the specific quota.
serviceCode (string) --
The service code identifying the originating service.
ServiceFailureException (dict) --
An unknown condition has caused a service failure.
message (string) --
ThrottlingException (dict) --
An exception indicating the request was throttled.
message (string) --
throttlingReasons (list) --
A list of reasons explaining why the request was throttled.
(dict) --
Provides information about a specific throttling reason.
reason (string) --
The reason code explaining why the request was throttled.
resource (string) --
The resource that caused the throttling.