Porcupine Model API

The Porcupine Model API trains a Wake Word model from a phrase. Send a phrase as a request and receive a trained .ppn model file in response, ready for on-device inference with Porcupine.

Base URL

All routes are relative to the following base URL:

https://rest.picovoice.ai

Authentication

Every request must be authenticated with your AccessKey passed in the x-api-key header. You can obtain a free AccessKey from the Picovoice Console.

x-api-key: ${ACCESS_KEY}

Requests made without a valid AccessKey are rejected with a 403 Forbidden response.

Train a Wake Word Model

POST /{language}/api/ppn

Trains a Porcupine wake word model for the given language and target platform from a phrase. On success, the response body is the binary .ppn model file.

Path Parameters

• language string — The language of the phrase. Must be one of the supported language values (e.g. en).

Headers

• x-api-key string — Required. Your AccessKey from the Picovoice Console.

Body Parameters

The request body is a JSON object with the following fields:

• platform string — Required. The target platform the model will run on. Must be one of the supported platform values.
• phrase string — Required. The wake word phrase to train the model on (e.g. Hey Computer).

Example Request

A successful request returns a 303 See Other redirect pointing to the trained model. The -L flag tells curl to follow that redirect automatically and download the .ppn file:

curl -L \
  -H "x-api-key: ${ACCESS_KEY}" \
  -o "${OUTPUT_PATH}" \
  -d '{"platform": "${PLATFORM}", "phrase": "${PHRASE}"}' \
  "https://rest.picovoice.ai/${LANGUAGE}/api/ppn"

Replace the placeholders with your own values:

• ${ACCESS_KEY} — your AccessKey from the Picovoice Console.
• ${OUTPUT_PATH} — the local path to write the returned .ppn model to (e.g. ./wake_word.ppn).
• ${PLATFORM} — a supported platform value (e.g. linux).
• ${PHRASE} — the wake word phrase to train the model on (e.g. Hey Computer).
• ${LANGUAGE} — a supported language value (e.g. en).

Responses

• 200 OK — Returned when the 303 redirect is followed. The response body is the binary .ppn model file.
• 303 See Other — Training succeeded. The response carries a Location header with a URL to the trained model. Follow this redirect (e.g. with curl -L) to download it and receive the 200 OK above.
• 400 Bad Request — The request was malformed, the platform value was invalid, or the phrase was missing or invalid.
• 403 Forbidden — The AccessKey is missing or invalid.

Supported Languages

The language path parameter accepts one of the following values:

Supported Platforms

The platform body parameter accepts one of the following values: