Class: Aws::Polly::Client
- Inherits:
-
Seahorse::Client::Base
- Object
- Seahorse::Client::Base
- Aws::Polly::Client
- Includes:
- ClientStubs
- Defined in:
- gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb
Overview
An API client for Polly. To construct a client, you need to configure a :region and :credentials.
client = Aws::Polly::Client.new(
region: region_name,
credentials: credentials,
# ...
)
For details on configuring region and credentials see the developer guide.
See #initialize for a full list of supported configuration options.
Instance Attribute Summary
Attributes inherited from Seahorse::Client::Base
API Operations collapse
-
#create_voice(params = {}) ⇒ Types::CreateVoiceOutput
Creates a custom voice from recordings of a speaker and returns it in
pendingstatus. -
#delete_lexicon(params = {}) ⇒ Struct
Deletes the specified pronunciation lexicon stored in an Amazon Web Services Region.
-
#delete_voice(params = {}) ⇒ Struct
Deletes a custom voice.
-
#describe_voices(params = {}) ⇒ Types::DescribeVoicesOutput
Returns the list of voices: the voices that Amazon Polly provides and the custom voices in your account.
-
#get_lexicon(params = {}) ⇒ Types::GetLexiconOutput
Returns the content of the specified pronunciation lexicon stored in an Amazon Web Services Region.
-
#get_speech_synthesis_task(params = {}) ⇒ Types::GetSpeechSynthesisTaskOutput
Retrieves a specific SpeechSynthesisTask object based on its TaskID.
-
#get_voice(params = {}) ⇒ Types::GetVoiceOutput
Returns the status and properties of a custom voice.
-
#list_lexicons(params = {}) ⇒ Types::ListLexiconsOutput
Returns a list of pronunciation lexicons stored in an Amazon Web Services Region.
-
#list_speech_synthesis_tasks(params = {}) ⇒ Types::ListSpeechSynthesisTasksOutput
Returns a list of SpeechSynthesisTask objects ordered by their creation date.
-
#list_tags_for_resource(params = {}) ⇒ Types::ListTagsForResourceOutput
Lists the tags for an Amazon Polly resource.
-
#put_lexicon(params = {}) ⇒ Struct
Stores a pronunciation lexicon in an Amazon Web Services Region.
-
#start_speech_synthesis_task(params = {}) ⇒ Types::StartSpeechSynthesisTaskOutput
Starts an asynchronous synthesis task by creating a new
SpeechSynthesisTask. -
#synthesize_speech(params = {}) ⇒ Types::SynthesizeSpeechOutput
Synthesizes UTF-8 input, plain text or SSML, to a stream of bytes.
-
#tag_resource(params = {}) ⇒ Struct
Adds specified tags to a resource with the specified ARN.
-
#untag_resource(params = {}) ⇒ Struct
Deletes specified tags from a resource.
Instance Method Summary collapse
-
#initialize(options) ⇒ Client
constructor
A new instance of Client.
-
#wait_until(waiter_name, params = {}, options = {}) {|w.waiter| ... } ⇒ Boolean
Polls an API operation until a resource enters a desired state.
Methods included from ClientStubs
#api_requests, #stub_data, #stub_responses
Methods inherited from Seahorse::Client::Base
add_plugin, api, clear_plugins, define, new, #operation_names, plugins, remove_plugin, set_api, set_plugins
Methods included from Seahorse::Client::HandlerBuilder
#handle, #handle_request, #handle_response
Constructor Details
#initialize(options) ⇒ Client
Returns a new instance of Client.
490 491 492 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 490 def initialize(*args) super end |
Instance Method Details
#create_voice(params = {}) ⇒ Types::CreateVoiceOutput
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.
635 636 637 638 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 635 def create_voice(params = {}, = {}) req = build_request(:create_voice, params) req.send_request() end |
#delete_lexicon(params = {}) ⇒ Struct
Deletes the specified pronunciation lexicon stored in an Amazon Web
Services Region. A lexicon which has been deleted is not available for
speech synthesis, nor is it possible to retrieve it using either the
GetLexicon or ListLexicon APIs.
For more information, see Managing Lexicons.
680 681 682 683 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 680 def delete_lexicon(params = {}, = {}) req = build_request(:delete_lexicon, params) req.send_request() end |
#delete_voice(params = {}) ⇒ Struct
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.
714 715 716 717 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 714 def delete_voice(params = {}, = {}) req = build_request(:delete_voice, params) req.send_request() end |
#describe_voices(params = {}) ⇒ Types::DescribeVoicesOutput
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.
859 860 861 862 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 859 def describe_voices(params = {}, = {}) req = build_request(:describe_voices, params) req.send_request() end |
#get_lexicon(params = {}) ⇒ Types::GetLexiconOutput
Returns the content of the specified pronunciation lexicon stored in an Amazon Web Services Region. For more information, see Managing Lexicons.
926 927 928 929 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 926 def get_lexicon(params = {}, = {}) req = build_request(:get_lexicon, params) req.send_request() end |
#get_speech_synthesis_task(params = {}) ⇒ Types::GetSpeechSynthesisTaskOutput
Retrieves a specific SpeechSynthesisTask object based on its TaskID. This object contains information about the given speech synthesis task, including the status of the task, and a link to the S3 bucket containing the output of the task.
973 974 975 976 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 973 def get_speech_synthesis_task(params = {}, = {}) req = build_request(:get_speech_synthesis_task, params) req.send_request() end |
#get_voice(params = {}) ⇒ Types::GetVoiceOutput
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.
The following waiters are defined for this operation (see #wait_until for detailed usage):
- voice_active
1036 1037 1038 1039 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1036 def get_voice(params = {}, = {}) req = build_request(:get_voice, params) req.send_request() end |
#list_lexicons(params = {}) ⇒ Types::ListLexiconsOutput
Returns a list of pronunciation lexicons stored in an Amazon Web Services Region. For more information, see Managing Lexicons.
1105 1106 1107 1108 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1105 def list_lexicons(params = {}, = {}) req = build_request(:list_lexicons, params) req.send_request() end |
#list_speech_synthesis_tasks(params = {}) ⇒ Types::ListSpeechSynthesisTasksOutput
Returns a list of SpeechSynthesisTask objects ordered by their creation date. This operation can filter the tasks by their status, for example, allowing users to list only tasks that are completed.
The returned response is a pageable response and is Enumerable. For details on usage see PageableResponse.
1165 1166 1167 1168 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1165 def list_speech_synthesis_tasks(params = {}, = {}) req = build_request(:list_speech_synthesis_tasks, params) req.send_request() end |
#list_tags_for_resource(params = {}) ⇒ Types::ListTagsForResourceOutput
Lists the tags for an Amazon Polly resource.
1212 1213 1214 1215 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1212 def (params = {}, = {}) req = build_request(:list_tags_for_resource, params) req.send_request() end |
#put_lexicon(params = {}) ⇒ Struct
Stores a pronunciation lexicon in an Amazon Web Services Region. If a lexicon with the same name already exists in the region, it is overwritten by the new lexicon. Lexicon operations have eventual consistency, therefore, it might take some time before the lexicon is available to the SynthesizeSpeech operation.
Overwriting a lexicon keeps its existing tags. You can specify tags
only when you create a lexicon. If you specify tags for a lexicon that
already exists, the request fails with a ValidationException. To
change the tags of an existing lexicon, use TagResource and
UntagResource.
For more information, see Managing Lexicons.
1281 1282 1283 1284 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1281 def put_lexicon(params = {}, = {}) req = build_request(:put_lexicon, params) req.send_request() end |
#start_speech_synthesis_task(params = {}) ⇒ Types::StartSpeechSynthesisTaskOutput
Starts an asynchronous synthesis task by creating a new
SpeechSynthesisTask. This operation requires all the standard
information needed for speech synthesis, plus the name of an Amazon S3
bucket for the service to store the output of the synthesis task and
two optional parameters (OutputS3KeyPrefix and SnsTopicArn). After
Amazon Polly creates the synthesis task, the operation returns a
SpeechSynthesisTask object that includes an identifier for the task
and its current status. The SpeechSynthesisTask object is available
for 72 hours after you start the asynchronous synthesis task.
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
disable the key or schedule it for deletion before the task runs, the
task fails and TaskStatusReason describes the cause.
1424 1425 1426 1427 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1424 def start_speech_synthesis_task(params = {}, = {}) req = build_request(:start_speech_synthesis_task, params) req.send_request() end |
#synthesize_speech(params = {}) ⇒ Types::SynthesizeSpeechOutput
Synthesizes UTF-8 input, plain text or SSML, to a stream of bytes. SSML input must be valid, well-formed SSML. Some alphabets might not be available with all the voices (for example, Cyrillic might not be read at all by English voices) unless phoneme mapping is used. For more information, see How it Works.
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.
1595 1596 1597 1598 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1595 def synthesize_speech(params = {}, = {}, &block) req = build_request(:synthesize_speech, params) req.send_request(, &block) end |
#tag_resource(params = {}) ⇒ Struct
Adds specified tags to a resource with the specified ARN. Existing tags on a resource are not changed if they are not specified in the request parameters. If you specify a tag key that already exists on the resource, the value in the request replaces the existing value.
1646 1647 1648 1649 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1646 def tag_resource(params = {}, = {}) req = build_request(:tag_resource, params) req.send_request() end |
#untag_resource(params = {}) ⇒ Struct
Deletes specified tags from a resource.
1689 1690 1691 1692 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1689 def untag_resource(params = {}, = {}) req = build_request(:untag_resource, params) req.send_request() end |
#wait_until(waiter_name, params = {}, options = {}) {|w.waiter| ... } ⇒ Boolean
Polls an API operation until a resource enters a desired state.
Basic Usage
A waiter will call an API operation until:
- It is successful
- It enters a terminal state
- It makes the maximum number of attempts
In between attempts, the waiter will sleep.
# polls in a loop, sleeping between attempts
client.wait_until(waiter_name, params)
Configuration
You can configure the maximum number of polling attempts, and the delay (in seconds) between each polling attempt. You can pass configuration as the final arguments hash.
# poll for ~25 seconds
client.wait_until(waiter_name, params, {
max_attempts: 5,
delay: 5,
})
Callbacks
You can be notified before each polling attempt and before each
delay. If you throw :success or :failure from these callbacks,
it will terminate the waiter.
started_at = Time.now
client.wait_until(waiter_name, params, {
# disable max attempts
max_attempts: nil,
# poll for 1 hour, instead of a number of attempts
before_wait: -> (attempts, response) do
throw :failure if Time.now - started_at > 3600
end
})
Handling Errors
When a waiter is unsuccessful, it will raise an error. All of the failure errors extend from Waiters::Errors::WaiterFailed.
begin
client.wait_until(...)
rescue Aws::Waiters::Errors::WaiterFailed
# resource did not enter the desired state in time
end
Valid Waiters
The following table lists the valid waiter names, the operations they call,
and the default :delay and :max_attempts values.
| waiter_name | params | :delay | :max_attempts |
|---|---|---|---|
| voice_active | #get_voice | 15 | 480 |
1804 1805 1806 1807 1808 |
# File 'gems/aws-sdk-polly/lib/aws-sdk-polly/client.rb', line 1804 def wait_until(waiter_name, params = {}, = {}) w = waiter(waiter_name, ) yield(w.waiter) if block_given? # deprecated w.wait(params) end |