API Documentation

Complete guide to using the Entaiwian Text Converter API

Back to Converter

Overview

The Entaiwian Text Converter API transforms encoded text into Traditional Chinese characters through a multi-step process:

  1. Gibberish → Zhuyin: Convert encoded input to Chinese phonetic symbols
  2. Zhuyin → Pinyin: Transform phonetic symbols to romanized pronunciation with tones
  3. Pinyin → Chinese: Convert to Chinese characters using tone matching
  4. Simplified → Traditional: Transform to Traditional Chinese characters

Base URL

Loading...

All API endpoints are relative to this base URL.

POST /convert

Convert encoded text to Traditional Chinese characters.

Request Body
{
  "text": "c96y7ap7ji3yji4tj x96xk7",
  "for_each": //True or False
}
Parameters
Field Type Required Description
text string Yes Encoded text to convert (max 1000 characters)
Response (Success)
{
  "result": "你好世界", //for_each: True -> {'ㄋㄧˇ': [('你', 1), ('擬', 1), ('尼', 0), ('逆', 0), ('泥', 0), ('匿', 0), ('暱', 0), ('霓', 0), ('妮', 0), ('溺', 0)], 'ㄏㄠˇ': [('好', 1), ('毫', 0), ('號', 0), ('豪', 0), ('耗', 0), ('浩', 0), ('嚎', 0), ('皓', 0), ('昊', 0), ('壕', 0)], 'ㄕˋ': [('是', 1), ('市', 1), ('事', 1), ('世', 1), ('視', 1), ('時', 0), ('實', 0), ('使', 0), ('十', 0), ('失', 0)], 'ㄐㄧㄝˋ': [('介', 1), ('借', 1), ('界', 1), ('結', 0), ('解', 0), ('接', 0), ('節', 0), ('階', 0), ('街', 0), ('姐', 0)]}
  "order": ['ㄋㄧˇ', 'ㄏㄠˇ', 'ㄕˋ', 'ㄐㄧㄝˋ']
  "processing_time": 0.123,
  "input_length": 24,
  "output_length": 4
}
Response Fields
Field Type Description
result string || for_each: True -> {string: [(string, int)]} Converted Traditional Chinese text
order [string] the order of zhuyin
processing_time number Time taken to process the request (seconds)
input_length integer Length of input text
output_length integer Length of converted text
cURL Example
curl -X POST LOADING.../convert \
  -H "Content-Type: application/json" \
  -d '{"text": "c96y7ap7ji3yji4tj x96xk7"}'
JavaScript Example
const response = await fetch('LOADING.../convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'c96y7ap7ji3yji4tj x96xk7'
  })
});

const data = await response.json();
console.log(data.result); // "你好世界"

GET /health

Check the health status of the API service.

Response
{
  "status": "healthy",
  "service": "Entaiwian Text Converter API",
  "timestamp": 1641234567.89
}

GET /docs

Access this API documentation page.

Response

HTML documentation page (this page)

Error Responses

Status Code Error Type Description Example Response
400 Bad Request Invalid request format or missing fields {"error": "Missing required field", "details": "Request must include 'text' field"}
422 Unprocessable Entity Conversion failed due to invalid input format {"error": "Conversion failed", "details": "Unable to convert the provided text..."}
429 Rate Limit Exceeded Too many requests from the same IP {"error": "Rate limit exceeded. Please try again later."}
500 Internal Server Error Unexpected server error during processing {"error": "Internal conversion error", "details": "...", "processing_time": 0.05}

Rate Limiting

The API is rate-limited to 50 requests per hour per IP address to ensure fair usage and service stability.

When the rate limit is exceeded, the API will return a 429 Too Many Requests status code. Please implement appropriate retry logic with exponential backoff in your applications.

Testing the API

You can test the API using various methods:

Web Interface

Use the main converter page for interactive testing.

Try It Now
Command Line

Use cURL or similar tools to test API endpoints.

Programming

Integrate the API into your applications using HTTP libraries.

Built with Flask and Bootstrap