Examples

Below you can find examples on how to use the Pūwhakahua API, which is a simple JSON-based REST API.

The following commands and code snippets assume the following environment variables to be set:

• PUWHAKAHUA_API_KEY - your API Key
• PUWHAKAHUA_API_URL - only if the API server is not the official one

curl

List voices

The following code queries for the available voice models and outputs the JSON array that the API returns:

curl -X GET https://api.puwhakahua.nz/voices \
    -H "x-api-key: $PUWHAKAHUA_API_KEY"

Synthesize

Generate speech and play it:

curl -X POST https://api.puwhakahua.nz/synthesize \
    -H "x-api-key: $PUWHAKAHUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"voice": "waikato-maniapoto", "text": "Kia ora koutou."}' \
    | aplay

Generate speech and save it to a file:

curl -X POST https://api.puwhakahua.nz/synthesize \
    -H "x-api-key: $PUWHAKAHUA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"voice": "waikato-maniapoto", "text": "Kia ora koutou."}' \
    > kia_ora.wav

Python

You can access the Pūwhakahua API via our Python client library. You can either use the ready-to-use command-line tools or use it as a Python library in your own projects.

Installation

• Linux

python3 -m venv venv
./venv/bin/pip install git+https://github.com/puwhakahua/puwhakahua-python-client.git

• Windows

python -m venv venv
.\venv\Scripts\pip install git+https://github.com/puwhakahua/puwhakahua-python-client.git

You can activate the virtual environment as follows:

• Linux

. ./venv/bin/activate

• Windows

.\venv\Scripts\activate

List voices (code)

The following code queries for the available voice models and outputs the generated list of names:

import json
from io import StringIO
from puwhakahua.client import list_voices

buffer = StringIO()
if list_voices(output=buffer):
    d = json.loads(buffer.getvalue())
    print(d)

List voices (command-line client)

The list-voices sub-command of the client allows you to list all the available voice models that the API has on offer:

puwhakahua-client list-voices

Here is an example JSON output:

[
  "waikato-maniapoto"
]

Synthesize (code)

Generate speech and play it:

from puwhakahua.client import synthesize

voice = "waikato-maniapoto"
text = "Kia ora koutou."
synthesize(voice, text, play_audio=True)

Generate speech and save it to a file:

from puwhakahua.client import synthesize
from playsound import playsound

voice = "waikato-maniapoto"
text = "Kia ora koutou."
if synthesize(voice, text, output="./kia_ora.wav"):
    print("Generated WAV file")
else:
    print("Something went wrong")

Synthesize (command-line client)

The following command uses the model waikato-maniapoto to generate speech from the text prompt Kia ora koutou and plays it back to the user:

puwhakahua-client synthesize -v "waikato-maniapoto" -t "Kia ora koutou." -p

This code saves the generated audio fragment to a WAV file:

puwhakahua-client synthesize -v "waikato-maniapoto" -t "Kia ora koutou." -o kia_ora.wav