Hán-Việt Reader API

Convert Chinese text to Hán-Việt (Sino-Vietnamese) readings and pinyin by word, with traditional / simplified forms; or find characters by reading.

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

Text▶ Try it online

Send Chinese text (simplified or traditional, up to 1,000 characters) and get the Hán-Việt reading, the pinyin, the traditional and the simplified spelling, and the segments: each word with its reading, pinyin and English glosses. The text is segmented by longest match against about 7,600 Sino-Vietnamese words (愛國 → ái quốc, 銀行 → ngân hàng) and the 125,000 words of CC-CEDICT, so polyphonic characters take the reading of the word they belong to whenever it is known (行動 hành động, 銀行 ngân hàng); other characters take their main reading, and every reading of a single character is listed.

Reverse lookup: reading=ái lists the characters read "ái", main reading first (ignore_tones=true to match without tones). details=true adds every character with all its Hán-Việt and Hán-Nôm readings, pinyin and variants. Characters with no known reading are listed in unknown_characters.

Data: Hán-Việt readings from the Unicode Unihan database (kVietnamese, Unicode License) completed with Wiktionary (CC BY-SA 4.0); pinyin from Unihan and CC-CEDICT (CC BY-SA 4.0, mdbg.net); rebuilt weekly. The attribution is included in every answer. Readings are a study aid: classical texts sometimes use a reading other than the main one.

Parameters

Name	In	Type	Required	Default
`text`	query\|body	string	no		Chinese text, simplified or traditional (max 1,000 characters).
`reading`	query\|body	string	no		Reverse lookup: a Hán-Việt syllable (e.g. `ái`); `ignore_tones=true` to match without tones, `limit` (default 100).
`details`	query\|body	boolean	no	`false`	Add every character with all readings, pinyin and variants.
`words`	query\|body	boolean	no	`true`	Use CC-CEDICT words for segmentation, pinyin and English glosses.

Example

curl "https://apibox.io.vn/v1/vn-hanviet?text=%E6%88%91%E7%88%B1%E8%B6%8A%E5%8D%97" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/vn-hanviet?text=%E6%88%91%E7%88%B1%E8%B6%8A%E5%8D%97', {
  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-hanviet?text=%E6%88%91%E7%88%B1%E8%B6%8A%E5%8D%97",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/vn-hanviet?text=%E6%88%91%E7%88%B1%E8%B6%8A%E5%8D%97');
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

{
  "text": "我爱越南",
  "han_viet": "ngã ái việt nam",
  "pinyin": "wǒ ài yuè nán",
  "traditional": "我愛越南",
  "simplified": "我爱越南",
  "segments": [
    {
      "text": "我",
      "han_viet": "ngã",
      "pinyin": "wǒ",
      "traditional": "我",
      "simplified": "我",
      "source": "character",
      "english": [
        "I; me; my"
      ],
      "readings": [
        "ngã",
        "ngả"
      ]
    },
    {
      "text": "爱",
      "han_viet": "ái",
      "pinyin": "ài",
      "traditional": "愛",
      "simplified": "爱",
      "source": "traditional variant",
      "english": [
        "to love; to be fond of; to like",
        "affection",
        "to be inclined (to do sth); to tend to (happen)"
      ],
      "readings": [
        "ái"
      ]
    },
    {
      "text": "越南",
      "han_viet": "việt nam",
      "pinyin": "yuè nán",
      "traditional": "越南",
      "simplified": "越南",
      "source": "compound",
      "english": [
        "Vietnam"
      ]
    }
  ],
  "unknown_characters": [],
  "note": "Hán-Việt readings of whole words come from Sino-Vietnamese words in Wiktionary; other characters take their main reading, which may not fit the context.",
  "attribution": {
    "sources": [
      {
        "name": "Unicode Unihan database",
        "version": "18.0.0",
        "license": "Unicode License v3",
        "url": "https://www.unicode.org/charts/unihan.html"
      },
      {
        "name": "Wiktionary (Vietnamese entries, via wiktextract / kaikki.org)",
        "license": "CC BY-SA 4.0",
        "url": "https://en.wiktionary.org"
      },
      {
        "name": "CC-CEDICT",
        "version": "2026-11-10",
        "license": "CC BY-SA 4.0",
        "url": "https://www.mdbg.net/chinese/dictionary?page=cedict"
      }
    ],
    "built_at": "2026-11-11"
  }
}

Use cases

Show Hán-Việt readings in a Chinese-learning app (HSK)
Read Chinese names and place names in Vietnamese
Help translators of Chinese novels with Sino-Vietnamese terms
Look up characters for family records, couplets and Hán Nôm research

FAQ

How are polyphonic characters handled?

Words are matched first: a character inside a known Sino-Vietnamese word or a CC-CEDICT word gets the reading and pinyin of that word; a character alone gets its main reading, with the other readings listed.

Simplified or traditional?

Both: simplified characters are mapped to their traditional forms to find the Hán-Việt word, and both spellings are returned.

Can I use the data commercially?

Yes: Unihan is under the Unicode License and Wiktionary and CC-CEDICT under CC BY-SA 4.0, which allow commercial use with attribution; keep the attribution field when you display results.

Hán-Việt Reader API

Parameters

Example

Response

Use cases

FAQ

Related APIs

Text Diff

Slugify

Text Statistics