CreateVoice
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.
Request Syntax
POST /v1/voices HTTP/1.1
Content-type: application/json
{
"ClientToken": "string",
"CustomerManagedEncryption": {
"EncryptionContext": {
"string" : "string"
},
"KmsKeyArn": "string"
},
"LanguageCode": "string",
"Name": "string",
"Tags": {
"string" : "string"
},
"TermsAccepted": boolean,
"VoiceCreationData": {
"Recordings": [
{
"Data": {
"Bytes": blob,
"S3Url": "string"
},
"Format": "string"
}
]
}
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- ClientToken
-
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request. If you don't specify a client token, the AWS 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.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
^[!-~]+$Required: No
- CustomerManagedEncryption
-
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 AWS owned key.
Type: CustomerManagedEncryption object
Required: No
- LanguageCode
-
The language of the recordings, for example,
en-US. Amazon Polly doesn't detect the language from the recordings.Type: String
Valid Values:
de-DE | en-US | es-US | fr-FR | hi-IN | it-IT | pt-BRRequired: Yes
- Name
-
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.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 64.
Pattern:
^[a-zA-Z0-9_-]+$Required: Yes
- Tags
-
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.
Type: String to string map
Map Entries: Maximum number of 200 items.
Key Length Constraints: Minimum length of 1. Maximum length of 128.
Value Length Constraints: Minimum length of 0. Maximum length of 256.
Required: No
- TermsAccepted
-
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
trueto create a voice. Otherwise, the request fails withValidationException.Type: Boolean
Required: Yes
-
- VoiceCreationData
-
The recordings that Amazon Polly uses to create the voice.
Type: VoiceCreationData object
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"Voice": {
"AdditionalLanguageCodes": [ "string" ],
"Arn": "string",
"CreationTime": number,
"CustomerManagedEncryption": {
"EncryptionContext": {
"string" : "string"
},
"KmsKeyArn": "string"
},
"Gender": "string",
"Id": "string",
"LanguageCode": "string",
"LanguageName": "string",
"Name": "string",
"Origin": "string",
"Status": "string",
"StatusReason": "string",
"SupportedEngines": [ "string" ],
"VoiceCreationData": {
"Recordings": [
{
"Data": {
"Bytes": blob,
"S3Url": "string"
},
"Format": "string"
}
]
}
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
You don't have sufficient permissions to perform this action. For a custom voice that uses a customer managed key, Amazon Polly also returns this exception if you don't have the required AWS KMS permissions on the key.
HTTP Status Code: 403
- InvalidTagParameterException
-
The resource ARN or a tag in the request isn't valid. Specify the ARN of a supported resource in the AWS account and Region of the request. Tag keys can have a maximum length of 128 characters, and tag values can have a maximum length of 256 characters. Correct the ARN or the tags, and then try again.
HTTP Status Code: 400
- ServiceFailureException
-
An unknown condition has caused a service failure.
HTTP Status Code: 500
- ServiceQuotaExceededException
-
The request would cause a service quota to be exceeded.
- quotaCode
-
The quota code identifying the specific quota.
- serviceCode
-
The service code identifying the originating service.
HTTP Status Code: 402
- ThrottlingException
-
The request was denied because of request throttling.
- throttlingReasons
-
A list of reasons explaining why the request was throttled.
HTTP Status Code: 400
- TooManyTagsException
-
The list of tags on the resource is over the limit. The maximum number of tags that can be applied to a resource is 50. Remove unused tags or reduce the number of tags in the request, and then try again.
HTTP Status Code: 400
- ValidationException
-
The input fails to satisfy the constraints specified by the service.
- fields
-
The fields that caused the validation error.
- reason
-
The reason the request failed validation. If Amazon Polly can't use the AWS KMS key that you specified in
CreateVoice,fieldsnamesCustomerManagedEncryption.KmsKeyArnand 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.
HTTP Status Code: 400
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: