GSP222

Overview

The Text-to-Speech API lets you create audio files of machine-generated, or synthetic, human speech. You provide the content as text or Speech Synthesis Markup Language (SSML), specify a voice (a unique 'speaker' of a language with a distinctive tone and accent), and configure the output; the Text-to-Speech API returns to you the content that you sent as spoken word, audio data, delivered by the voice that you specified.

In this lab you use the Text-to-Speech API to create a series of audio files, then listen to them to compare the differences.

What you'll learn

In this lab you use the Text-to-Speech API to do the following:

• Create a series of audio files.
• Listen and compare audio files.
• Configure audio output.

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources are made available to you.

This hands-on lab lets you do the lab activities in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

Note: Use an Incognito (recommended) or private browser window to run this lab. This prevents conflicts between your personal account and the student account, which may cause extra charges incurred to your personal account.

• Time to complete the lab—remember, once you start, you cannot pause a lab.

Note: Use only the student account for this lab. If you use a different Google Cloud account, you may incur charges to that account.

How to start your lab and sign in to the Google Cloud console

1. Click the Start Lab button. If you need to pay for the lab, a dialog opens for you to select your payment method. On the left is the Lab Details pane with the following:

   • The Open Google Cloud console button
   • Time remaining
   • The temporary credentials that you must use for this lab
   • Other information, if needed, to step through this lab

2. Click Open Google Cloud console (or right-click and select Open Link in Incognito Window if you are running the Chrome browser).

   The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username below and paste it into the Sign in dialog.

   {{{user_0.username | "Username"}}}

   You can also find the Username in the Lab Details pane.

4. Click Next.

5. Copy the Password below and paste it into the Welcome dialog.

   {{{user_0.password | "Password"}}}

   You can also find the Password in the Lab Details pane.

6. Click Next.

   Important: You must use the credentials the lab provides you. Do not use your Google Cloud account credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

7. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Google Cloud console opens in this tab.

Note: To access Google Cloud products and services, click the Navigation menu or type the service or product name in the Search field.

Activate Cloud Shell

Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud. Cloud Shell provides command-line access to your Google Cloud resources.

1. Click Activate Cloud Shell at the top of the Google Cloud console.

2. Click through the following windows:

   • Continue through the Cloud Shell information window.
   • Authorize Cloud Shell to use your credentials to make Google Cloud API calls.

When you are connected, you are already authenticated, and the project is set to your Project_ID, . The output contains a line that declares the Project_ID for this session:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.

3. (Optional) You can list the active account name with this command:

gcloud auth list

4. Click Authorize.

Output:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Optional) You can list the project ID with this command:

gcloud config list project

Output:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Note: For full documentation of gcloud, in Google Cloud, refer to the gcloud CLI overview guide.

Set the region for your project

In Cloud Shell, enter the following command to set the region to run your project in this lab:

gcloud config set compute/region {{{project_0.default_region | Region}}}

Task 1. Enable the Text-to-Speech API

The Cloud Text-to-Speech API page shows details, metrics and more.

Enable the API:

1. In the Navigation menu (), click APIs and Services > Library.

2. Enter text-to-speech in the Search for APIs & Services box, then click Cloud Text-to-Speech API from the search results.

3. Click Enable to enable the Cloud Text-to-Speech API.

Wait a few seconds for the API to be enabled for the project.

Click Check my progress to verify the objective. Enable the Text-to-Speech API

Task 2. Create a virtual environment

Python virtual environments are used to isolate package installation from the system.

1. Install the virtualenv environment:

sudo apt-get install -y virtualenv

2. Build the virtual environment:

python3 -m venv venv

3. Activate the virtual environment:

source venv/bin/activate

Task 3. Create a service account

You use a service account to authenticate your calls to the Text-to-Speech API.

Create a service account:

1. Run the following command in Cloud Shell:

gcloud iam service-accounts create tts-qwiklab

2. Generate a key to use that service account:

gcloud iam service-accounts keys create tts-qwiklab.json --iam-account tts-qwiklab@{{{project_0.project_id | Project ID}}}.iam.gserviceaccount.com

3. Finally, set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of your key file:

export GOOGLE_APPLICATION_CREDENTIALS=tts-qwiklab.json

Click Check my progress to verify the objective. Create a service account

Task 4. Get a list of available voices

The Text-to-Speech API provides different voices and languages that you can use to create audio files. You can use any of the available voices as the speaker for your content.

Note: The Text-to-Speech API includes several premium voices, known as WaveNet voices, that generate more natural-sounding synthetic speech. These voices are also a bit more expensive than other available voices. Refer to the Cloud Text-to-Speech pricing page for more details.

1. Still in Cloud Shell, use the following curl command to list the voices available when you use the Text-to-Speech API to create synthetic speech:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://texttospeech.googleapis.com/v1/voices"

The Text-to-Speech API returns a JSON-formatted result that looks similar to the following:

{ "voices": [ { "languageCodes": [ "es-ES" ], "name": "es-ES-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 24000 }, { "languageCodes": [ "ja-JP" ], "name": "ja-JP-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 22050 }, { "languageCodes": [ "pt-BR" ], "name": "pt-BR-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 24000 }, ... ] }

In the curl command results, notice that each voice has four fields:

• name: The voice ID you provide to request that voice.
• ssmlGender: The gender of the voice to speak the text, as defined in the SSML W3 Recommendation.
• naturalSampleRateHertz: The sampling rate of the voice.
• languageCodes: The list of language codes associated with that voice.

Also notice that some languages have several voices to choose from.

2. Scope the results returned from the API to just a single language code:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://texttospeech.googleapis.com/v1/voices?language_code=en"

Task 5. Create synthetic speech from text

Now that you've seen how to get the names of voices to speak your text, it's time to create some synthetic speech!

Build your request

For this, use the Cloud Shell Editor to build your request to the Text-to-Speech API in a text file named synthesize-text.json.

1. In Cloud Shell, click Open Editor to open the Cloud Shell Editor.

2. In the action bar, click File > New file.

3. In the Select File Type or Enter File Name field, enter synthesize-text.json.

4. Click OK.

5. Add the following code to synthesize-text.json:

{ 'input':{ 'text':'Cloud Text-to-Speech API allows developers to include natural-sounding, synthetic human speech as playable audio in their applications. The Text-to-Speech API converts text or Speech Synthesis Markup Language (SSML) input into audio data like MP3 or LINEAR16 (the encoding used in WAV files).' }, 'voice':{ 'languageCode':'en-gb', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'audioEncoding':'MP3' } }

6. Click File > Save to save the file.

The JSON-formatted request provides three objects:

• input: Provides the text to translate into synthetic speech.
• voice: Object specifies the voice to use for the synthetic speech.
• audioConfig: Tells the Text-to-Speech API what kind of audio encoding to send back.

7. Click Open Terminal to return to the terminal.

8. Call the Text-to-Speech API:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-text.json "https://texttospeech.googleapis.com/v1/text:synthesize" \ > synthesize-text.txt

The output of this call is saved to a file called synthesize-text.txt.

9. Click Open Editor and open the synthesize-text.txt file. Notice that the Text-to-Speech API provides the audio output in base64-encoded text assigned to the audioContent field, similar to what's shown below:

{ "audioContent": "//NExAASGoHwABhGudEACdzqFXfRE4EY3AACkD/zX4ADf/6J/[...]" }

Translate the response

To translate the response into audio, you select the audio data synthesize-text.txt contains and decode it into an audio file - for this lab, an MP3 file. There are many ways to do this, this lab provides some simple Python code.

1. In the action bar, click File > New file.

2. In the Select File Type or Enter File Name field, type then enter tts_decode.py.

3. Click OK.

4. Type or copy the following into tts_decode.py:

import argparse from base64 import decodebytes import json """ Usage: python tts_decode.py --input "synthesize-text.txt" \ --output "synthesize-text-audio.mp3" """ def decode_tts_output(input_file, output_file): """ Decode output from Cloud Text-to-Speech. input_file: the response from Cloud Text-to-Speech output_file: the name of the audio file to create """ with open(input_file) as input: response = json.load(input) audio_data = response['audioContent'] with open(output_file, "wb") as new_file: new_file.write(decodebytes(audio_data.encode('utf-8'))) if __name__ == '__main__': parser = argparse.ArgumentParser( description="Decode output from Cloud Text-to-Speech", formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument('--input', help='The response from the Text-to-Speech API.', required=True) parser.add_argument('--output', help='The name of the audio file to create', required=True) args = parser.parse_args() decode_tts_output(args.input, args.output)

5. Save tts_decode.py.

Create and run the audio file

To create an audio file from the response you received from the Text-to-Speech API:

1. Click Open Terminal to return to Cloud Shell.

2. Create the audio file synthesize-text-audio.mp3:

python tts_decode.py --input "synthesize-text.txt" --output "synthesize-text-audio.mp3"

3. Click Open Editor to open the Cloud Shell Editor.

4. Click synthesize-text-audio.mp3 in the left pane to open the file.

5. Play the audio to listen to the file. You hear the synthetic voice speak the text that you provided to it!

Task 6. Create synthetic speech from SSML

In addition to using text, you can also provide input to the Text-to-Speech API in the form of Speech Synthesis Markup Language (SSML). SSML defines an XML format for representing synthetic speech. Using SSML input, you can more precisely control pauses, emphasis, pronunciation, pitch, speed, and other qualities in the synthetic speech output.

Build your request

First, build your request to the Text-to-Speech API in a text file titled synthesize-ssml.json.

1. Still in the Cloud Shell Editor, in the action bar, click File > New file.

2. In the Select File Type or Enter File Name field, type then enter synthesize-ssml.json.

3. Click OK.

4. Type or copy the following into synthesize-ssml.json:

{ 'input':{ 'ssml':'<speak><s> <emphasis level="moderate">Cloud Text-to-Speech API</emphasis> allows developers to include natural-sounding <break strength="x-weak"/> synthetic human speech as playable audio in their applications.</s> <s>The Text-to-Speech API converts text or <prosody rate="slow">Speech Synthesis Markup Language</prosody> <say-as interpret-as=\"characters\">SSML</say-as> input into audio data like <say-as interpret-as=\"characters\">MP3</say-as> or <sub alias="linear sixteen">LINEAR16</sub> <break strength="weak"/> (the encoding used in <sub alias="wave">WAV</sub> files).</s></speak>' }, 'voice':{ 'languageCode':'en-gb', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'audioEncoding':'MP3' } }

Notice that the input object of the JSON payload to send includes some different stuff this time around:

• Rather than a text field, the input object has a ssml field instead.
• The ssml field contains XML-formatted content with the <speak> element as its root.

Each of the elements present in this XML representation of the input affects the output of the synthetic speech.

Specifically, the elements in this sample have the following effects:

• <s> contains a sentence.
• <emphasis> adds stress on the enclosed word or phrase.
• <break> inserts a pause in the speech.
• <prosody> customizes the pitch, speaking rate, or volume of the enclosed text, as specified by the rate, pitch, or volume attributes.
• <say-as> provides more guidance about how to interpret and then say the enclosed text, for example, whether to speak a sequence of numbers as ordinal or cardinal.
• <sub> specifies a substitution value to speak for the enclosed text.

Note: You can see the full list of SSML elements supported by Cloud Text-to-Speech by reviewing the SSML reference.

3. Click Open Terminal to open the Cloud Shell terminal.

4. Call the Text-to-Speech API, and save the output to a file called synthesize-ssml.txt:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-ssml.json "https://texttospeech.googleapis.com/v1/text:synthesize" \ > synthesize-ssml.txt

Create and run the audio file

Again, you need to decode the output from the Text-to-Speech API before you can hear the audio.

1. Click Open Terminal. Run the following command to generate an audio file named synthesize-ssml-audio.mp3 using the tts_decode.py utility that you created previously:

python tts_decode.py --input "synthesize-ssml.txt" --output "synthesize-ssml-audio.mp3"

2. Click Open Editor.

3. Click synthesize-ssml-audio.mp3 in the left pane, then play the embedded audio file.

Notice the differences in the SSML output and the text file output: although both audio files say the same words, the SSML output speaks them a bit differently, adding pauses and different pronunciations for abbreviations.

Task 7. Configure audio output and device profiles

Going beyond SSML, you can provide even more customization to your synthetic speech output created by the Text-to-Speech API. You can specify other audio encodings, change the pitch of the audio output, and even request that the output be optimized for a specific type of hardware.

Build your request

Build your request to the Text-to-Speech API in a text file titled synthesize-with-settings.json:

1. In the action bar, click File > New file.

2. In the Select File Type or Enter File Name field, type then enter synthesize-with-settings.json.

3. Click OK.

4. Type or copy the following into synthesize-with-settings.json:

{ 'input':{ 'text':'The Text-to-Speech API is ideal for any application that plays audio of human speech to users. It allows you to convert arbitrary strings, words, and sentences into the sound of a person speaking the same things.' }, 'voice':{ 'languageCode':'en-us', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'speakingRate': 1.15, 'pitch': -2, 'audioEncoding':'OGG_OPUS', 'effectsProfileId': ['headphone-class-device'] } }

5. Save the file.

Notice the audioConfig object now contains additional fields:

• The speakingRate field specifies a speed at which the speaker says the voice. A value of 1.0 is the normal speed for the voice, 0.5 is half that fast, and 2.0 is twice as fast.
• The pitch field specifies a difference in tone to speak the words. The value here specifies a number of semitones lower (negative) or higher (positive) to speak the words.
• The audioEncoding field specifies the audio encoding to use for the data. The accepted values for this field are LINEAR16, MP3, and OGG_OPUS.
• The effectsProfileId field requests that the Text-to-Speech API optimizes the audio output for a specific playback device. The API applies an predefined audio profile to the output that enhances the audio quality on the specified class of devices.

Note: The Audio Profiles feature is in Beta release status. Review the guide for details about how to use it in your application. All other settings described here are generally available for normal use in your application.

4. Click Open Terminal.

5. Call the Text-to-Speech API:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-with-settings.json "https://texttospeech.googleapis.com/v1beta1/text:synthesize" \ > synthesize-with-settings.txt

The output of this call is saved to a file called synthesize-with-settings.txt.

Create and run the audio file

1. Run the following command to generate an audio file named synthesize-with-settings-audio.mp3 from the output received from the Text-to-Speech API:

python tts_decode.py --input "synthesize-with-settings.txt" --output "synthesize-with-settings-audio.ogg"

2. Click Open Editor to open the Cloud Shell Editor.

3. Click synthesize-with-settings-audio.mp3 in the left pane to open the file and then play the audio.

4. Play the synthesize-with-settings-audio.mp3 audio file as well as the other audio files you created in this lab. Notice that the voice on the audio speaks a bit faster and lower than the other audio files.

Congratulations!

You have learned how to create synthetic speech using the Cloud Text-to-Speech API. You learned about:

• Listing all of the synthetic voices available through the Text-to-Speech API
• Creating a Text-to-Speech API request and calling the API with curl, providing both text and SSML
• Configuring the setting for audio output, including specifying a device profile for audio playback

Next steps / Learn more

• Check out the detailed documentation for the Text-to-Speech API on cloud.google.com.
• Learn how to create synthetic speech using the client libraries for the Text-to-Speech API.

Google Cloud training and certification

...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.

Manual Last Updated August 5, 2025

Lab Last Tested November 04, 2024

Copyright 2025 Google LLC. All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.