Create a Multi-Turn Scripted Conversation with the PlayDialog API
PlayDialog API Guide
This guide provides a step-by-step approach to using the PlayDialog API to create a multi-turn scripted conversation between two distinct speakers.
In this example, we’ll have PlayDialog create a scripted conversation between two speakers - Country Mouse
and Town Mouse
.
Prerequisites
- Access credentials (Secret key and User ID) for the PlayDialog API.
- Python environment for executing the API request.
Setup your API Key
To keep your API key secure and avoid hardcoding it directly into your code, you can store it as an environment variable. This way, your script can access it securely without exposing the key.
Step 1: Set the Environment Variable
For macOS and Linux
- Open your terminal.
- Add this line to your ~/.bashrc or ~/.zshrc file to make it persistent across sessions
- Run
~/.bashrc (or source ~/.zshrc for zsh)
to load the variables into your current session.
For Windows
- Open Command Prompt or PowerShell.
- Use the
setx
command to create each environment variable individually:
- Restart your terminal to apply the changes.
Step 2: Access the Variables in Python
In your Python script, use the os module to access the environment variables:
Key API Parameters
The following API payload define the conversation, speaker details, and audio generation options:
model
: Specifies the PlayDialog API model to be used. Here,PlayDialog
supports multi-turn conversation generation.text
: Contains the scripted conversation, with each turn prefixed by the speaker’s name (e.g.,"Country Mouse"
&"Town Mouse"
).voice
: URL path to the voice manifest for the first speaker.voice_2
: URL path to the voice manifest for the second speaker.turn_prefix
/turn_prefix_2
: Used to specify each speaker’s dialogue turns within thetext
field. For example:turn_prefix
saysCountry Mouse
to indicate the position where Speaker 1’s dialogue andturn_prefix_2
saysTown Mouse
that indicates the position where Speaker 2’s dialogue parts are.output_format
: Format for the generated audio file, typicallywav
ormp3
.
Call the API
The following Python script demonstrates how to request the PlayDialog API and save the generated audio file.
If you happen to save the code as country_mouse.py
then Run the code using python3 country_mouse.py
pointing your terminal to the directory where the country_mouse.py
file is stored. This will save the dialogue.wav
in the same working directory.
Code Explanation
This script uses the PlayDialog API to generate a multi-turn conversation between two characters. The AUTHORIZATION token
and X-USER-ID
are required for authentication, which you’ll need to replace with your own credentials.
Each line of dialogue is labeled by character name (e.g., “Country Mouse
” or “Town Mouse
”) to simulate a natural conversation. The script assigns a unique voice to each character using voice
and voice2
. On a successful API call, the generated audio is saved as dialogue.wav
. Any errors are reported with status details.
To run the script:
- Replace placeholders in the headers with your API key and user ID.
- Update the
text
with your scripted conversation - Update the Speaker Details and their respective voices
- Run the script. If successful, an audio file,
dialogue.wav
, will be saved in the current directory, capturing the dialogue as configured. - This setup can easily adapt to more complex dialogues or different speakers.
Troubleshooting
- Authentication Issues: Verify your
API key
anduser ID
. Ensure theAUTHORIZATION
header includes “Bearer ” followed by your token. - API Endpoint Errors: Confirm you’re using the correct PlayDialog API endpoint URL and the
model
name isPlayDialog