Vietnamese Syllables & Poetry API

Q: What counts as a rhyme?

`exact` = same medial, vowel and final; `rhyme` = same vowel and final (hoa / xa); `near` = same final with a close vowel (vần thông, nhau / dâu). Poems also require both syllables to be bằng.

Split Vietnamese syllables into onset, medial, vowel, final and tone, get IPA for Northern, Central and Southern dialects, find rhymes and check poems.

GETPOSThttps://apibox.io.vn/v1/vn-syllable

Text▶ Try it online

Analyse Vietnamese text syllable by syllable: onset (phụ âm đầu), medial (âm đệm), nucleus (âm chính), final (âm cuối) and tone (thanh), whether the syllable is valid (spelling rules such as c/k/q, g/gh, ng/ngh, stop finals only with sắc or nặng, impossible rhymes), its tone class (bằng / trắc) and a broad IPA transcription for the Northern (Hà Nội), Central (Huế) and Southern (Sài Gòn) dialects, with tones in Chao digits.

action=rhyme compares a syllable with others (exact, rhyme = same vowel and final, near = vần thông) or lists rhyming syllables from the Vietnamese dictionary, filtered by tone class. action=poem checks a poem: lục bát (tones at positions 2-4-6 and 2-4-6-8, ngang / huyền contrast of syllables 6 and 8, rhyme of syllable 6 of the six-syllable line with syllable 6 of the eight-syllable line and of syllable 8 with the next line) or Tang-style seven-syllable poems (nhị tứ lục phân minh, đối and niêm, bằng rhymes at the end of lines 1, 2, 4, 6, 8).

The phonology follows Thompson (1965), Kirby (2011) and the dialect tables of Wikipedia "Vietnamese phonology"; transcriptions are approximate, one value per dialect. No data leaves the request.

Parameters

Name	In	Type	Required	Default
`text`	query\|body	string	no		Text to analyse (up to 500 syllables).
`action`	query\|body	string	no	`analyze`	`analyze`, `rhyme` or `poem`.
`syllable`	query\|body	string	no		rhyme: the syllable to match.
`compare`	query\|body	string	no		rhyme: syllables to compare, comma separated (otherwise rhymes from the dictionary).
`tone_class`	query\|body	string	no	`same`	rhyme: `same`, `bang`, `trac` or `any`.
`poem`	body	string	no		poem: one line per line (or separated by "/").
`form`	query\|body	string	no	`auto`	poem: `auto`, `luc_bat` or `that_ngon`.
`dialect`	query\|body	string	no	`all`	`north`, `central`, `south` or `all`.

Example

curl "https://apibox.io.vn/v1/vn-syllable?text=Ti%E1%BA%BFng%20Vi%E1%BB%87t" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-syllable?text=Ti%E1%BA%BFng%20Vi%E1%BB%87t', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/vn-syllable?text=Ti%E1%BA%BFng%20Vi%E1%BB%87t",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-syllable?text=Ti%E1%BA%BFng%20Vi%E1%BB%87t');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "action": "analyze",
  "count": 2,
  "valid": true,
  "syllables": [
    {
      "syllable": "Tiếng",
      "valid": true,
      "onset": "t",
      "medial": null,
      "nucleus": "iê",
      "coda": "ng",
      "rhyme_spelling": "iêng",
      "tone": "sac",
      "tone_vi": "sắc",
      "tone_class": "trac",
      "tone_class_vi": "trắc",
      "checked": false,
      "ipa": {
        "north": "tiəŋ35",
        "central": "tiən24",
        "south": "tiːn35"
      }
    },
    {
      "syllable": "Việt",
      "valid": true,
      "onset": "v",
      "medial": null,
      "nucleus": "iê",
      "coda": "t",
      "rhyme_spelling": "iêt",
      "tone": "nang",
      "tone_vi": "nặng",
      "tone_class": "trac",
      "tone_class_vi": "trắc",
      "checked": true,
      "ipa": {
        "north": "viət21",
        "central": "viət31",
        "south": "jiːt21"
      }
    }
  ],
  "ipa": {
    "north": "tiəŋ35 viət21",
    "central": "tiən24 viət31",
    "south": "tiːn35 jiːt21"
  },
  "tone_pattern": "TT",
  "references": [
    "L. C. Thompson, A Vietnamese Grammar (1965)",
    "J. Kirby, \"Vietnamese (Hanoi Vietnamese)\", JIPA 41(3):381–392 (2011)",
    "Wikipedia, \"Vietnamese phonology\" (tone values by dialect)"
  ],
  "note": "Broad, approximate transcription with one value per dialect; tones in Chao digits."
}

Use cases

Teach Vietnamese spelling and tones in a language-learning app
Find rhymes for song lyrics, slogans and poems
Check lục bát homework in a literature class app
Prepare phonetic input for TTS or NLP research

FAQ

Which dialects are transcribed?

Northern (Hà Nội), Central (Huế) and Southern (Sài Gòn), e.g. "Việt" = viət21 / viət31 / jiːt21. Values are broad and approximate.

What counts as a rhyme?

exact = same medial, vowel and final; rhyme = same vowel and final (hoa / xa); near = same final with a close vowel (vần thông, nhau / dâu). Poems also require both syllables to be bằng.

Which poem forms are checked?

Lục bát (6/8 lines) and seven-syllable Tang-style poems (tứ tuyệt, bát cú). form=auto picks seven-syllable rules when every line has 7 syllables.

Vietnamese Syllables & Poetry API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics