Score Pronunciation

Score Cantonese pronunciation by comparing audio against expected jyutping. This endpoint accepts an audio recording and a target Cantonese text, then returns a similarity score indicating how closely the pronunciation matches the expected jyutping.

Request Parameters

This endpoint requires multipart/form-data for file uploads.

Parameter	Type	Required	Description
api_key	string	Yes	Your API key for authentication
audio	file	Yes	Audio file of the user's pronunciation. Supported formats: wav, mp3, m4a, flac, ogg. Max size: 10MB.
text	string	Yes	The target Cantonese text to compare pronunciation against.

Example Request

Here are examples of how to score pronunciation using different programming languages.

to auto-fill your API key in the code examples below.

curl -X POST "https://cantonese.ai/api/learn-cantonese/score-pronunciation" \
  -F "api_key=YOUR_API_KEY" \
  -F "text=你好嗎" \
  -F "[email protected];type=audio/ogg"

Response

On success, the response returns a JSON object with the pronunciation score and jyutping comparison:

Response Fields

Field	Type	Description
success	boolean	Whether the request was processed successfully.
score	number	Pronunciation score from 0 to 100, where 100 is a perfect match.
expectedJyutping	string	The correct jyutping romanization for the target text.
transcribedJyutping	string	The jyutping transcribed from the audio recording.
passed	boolean	Whether the pronunciation passed (score >= 90).

High score response (pronunciation matches the target text):

{
  "success": true,
  "score": 95,
  "expectedJyutping": "nei5 hou2 maa3",
  "transcribedJyutping": "nei5 hou2 maa3",
  "passed": true
}

Low score response (pronunciation does not match the target text):

{
  "success": true,
  "score": 42,
  "expectedJyutping": "nei5 soeng2 dim2 aa3",
  "transcribedJyutping": "nei5 hou2 maa3",
  "passed": false
}

Status Codes

The API returns standard HTTP status codes to indicate the success or failure of requests.