Why Create Scripts?

API.audio offer tools for you to organise your content. Instead of creating speech directly from text via a direct call to the text-to-speech API, we recommend creating scripts. Script is text which normally would be spoken and recorded by a voice. API.audio offer ways for you to organise content efficiently, version it (eg for personalisation or to make it dynamic) and arrange it so it is ready for production.

Scripts allow you to organise and store your content, offering additional guard rails optimised to programmatically create professional sounding audio such as SSML tags, personalisation parameters and sound design annotation.

Simply create all your content as scripts, store the scriptIds for all scripts and produce speech directly on the fly. If you use personalisation parameters, you can simply reproduce speech by passing the chosen variable for a script already created. This reduces latency, makes it possible to switch speakers within the same track and access batteries-included parameters to personalise content or make it dynamic.

Example

Let's look through an example.
In this case we have a fitness app. We want to feed the app user feedback at the beginning of each session.
In this case we create each piece of text as a script. We only need to do that once for each piece.

Let's create one for motivation. We want to feed each user a personalised track, so we define the {{username}} parameter.

scriptName, moduleName and projectName are used to organise your content in a meaningful way. (Read more about the data model here)

#Create a script. Remember to import apiaudio and your API key 
script = apiaudio.Script.create(scriptText="You are almost at the finish line {{username}}",scriptName="motivation", moduleName="workout", projectName="fitness")
print(script)

After you've created a script, you can retrieve the scriptId. scriptId is a custom identifier for your script.

# Get the scriptId from the script created and store it 
scriptId = script.get("scriptId")

📘

Create several version of speech for the same script!

Now that you have created the script, you can simply use the scriptId to create speech on the fly without having to recreate a script. You can version it defining the audience parameter, or changing the speaker, speed or other parameters.

In this case we are producing the audio for a user named Maria.

# Create speech with that scriptId

response = apiaudio.Speech.create(
    scriptId="your_script_id",
    voice="Matthew",
    audience=[{"username": "Maria"}]
)
print(response)

And the last step- download your file!

# Download the file 
response = apiaudio.Speech.download(scriptId="your_script_id", parameters={"username": "Maria"})
print(response)