Text to Jyutping

Convert Chinese text to Jyutping romanization. This endpoint supports multiple output formats including plain text, character-by-character lists, annotated text, initial format, and IPA (International Phonetic Alphabet) representations.

Request Parameters

This endpoint accepts a JSON body with the following parameters:

Parameter	Type	Required	Description
text	string	Yes	The Chinese text to convert to Jyutping.
outputType	string	No	The output format. Defaults to `text`. See output types below.

Output Types

Value	Description	Result Type
text	Plain jyutping text separated by spaces	string
list	Character-by-character list with jyutping mappings	array
annotated	Text with inline jyutping annotations	string
initial_format	Jyutping with initial-final separation	string
ipa	International Phonetic Alphabet representation	string
ipa_list	Character-by-character list with IPA mappings	array
ipa_text	Plain IPA text separated by spaces	string

Example Request

Here are examples of how to convert text to jyutping using different programming languages.

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

curl -X POST "https://cantonese.ai/api/text-to-jyutping" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好嗎",
    "outputType": "text"
  }'

Response

On success, the response returns a JSON object with the conversion result. The format of the result field depends on the outputType parameter.

outputType = "text" (default):

{
  "success": true,
  "result": "nei5 hou2 maa3"
}

outputType = "list":

{
  "success": true,
  "result": [
    {
      "character": "你",
      "jyutping": "nei5"
    },
    {
      "character": "好",
      "jyutping": "hou2"
    },
    {
      "character": "嗎",
      "jyutping": "maa3"
    }
  ]
}

outputType = "annotated":

{
  "success": true,
  "result": "你(nei5)好(hou2)嗎(maa3)"
}

outputType = "initial_format":

{
  "success": true,
  "result": "n-ei5 h-ou2 m-aa3"
}

outputType = "ipa":

{
  "success": true,
  "result": "nei̯˩˧ hou̯˧˥ maː˧"
}

outputType = "ipa_list":

{
  "success": true,
  "result": [
    {
      "character": "你",
      "jyutping": "nei̯˩˧"
    },
    {
      "character": "好",
      "jyutping": "hou̯˧˥"
    },
    {
      "character": "嗎",
      "jyutping": "maː˧"
    }
  ]
}

outputType = "ipa_text":

{
  "success": true,
  "result": "nei̯˩˧ hou̯˧˥ maː˧"
}

Status Codes

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