Documentation

Make your first call in 5 minutes

Get a key, send a request, read the response — in that order.

1. Get an API key

Generate a free test key on the Get API Key page. New accounts receive testing quota automatically.在获取 API Key页面生成免费测试 Key。新账户将自动获得测试额度。

2. Send a request

curl -X POST https://api.chinesekey.org/v1/decompose \
  -H "Authorization: Bearer pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chars": "清",
    "mode": "full",
    "lang": "en",
    "include_family": true,
    "max_family": 12
  }'

3. Read the response

{
  "code": 0,
  "message": "success",
  "data": [{
    "char": "清",
    "pinyin": "qīng",
    "structure": { "type": "左右", "type_en": "left-right", "components": ["氵", "青"] },
    "semantic": { "component": "氵", "meaning": "水相关", "meaning_en": "related to water", "category": "水部" },
    "phonetic": { "component": "青", "hint": "读音相近（青 qīng）", "hint_en": "phonetic hint from 青 (qīng)" },
    "decomposition": { "full": "氵 + 青", "path": ["清", "氵+青", "青 → 龶+月"] },
    "families": {
      "semantic": [{"char":"江","pinyin":"jiāng"},{"char":"河","pinyin":"hé"}],
      "phonetic": [{"char":"情","pinyin":"qíng"},{"char":"晴","pinyin":"qíng"}]
    },
    "explanation": {
      "zh": "「清」由意符「氵」…",
      "en": "The character 清 consists of…"
    },
    "meta": { "confidence": 0.98, "source": "Chu Three-Books Algorithm", "version": "2026.08" }
  }],
  "usage": { "chars_processed": 1, "credits_used": 1 }
}

API Reference

Authentication & endpoint

—	Value
Protocol	HTTPS
Base URL	https://api.chinesekey.org
Endpoint	POST /v1/decompose (single characters may also use GET)
Auth header	Authorization: Bearer <your_api_key>
Content type	application/json
Rate limit	Free tier: 100 requests/day. Paid tiers: billed by usage.

Request parameters

Param	Type	Required	Description
chars	string / array	Yes	A single character or an array of characters (array recommended, supports batching)
mode	string	No	basic / full / family (default full)
lang	string	No	zh / en (default zh)
include_family	boolean	No	Whether to return the family list (default true)
max_family	integer	No	Max family members to return (default 20)

Response fields

The data[] array mirrors the decomposition card 1:1 — the semantic component is always semantic, the phonetic component is always phonetic, and both carry bilingual meaning fields. See the sample response above for the full shape.

Error codes

Code	Meaning	Suggested handling
4001	Invalid character	Show the error card: "Only Chinese characters are supported. Try 镜 or 安静."
4002	Batch limit exceeded	Prompt to reduce the batch size
4010	API key invalid or expired	Send the user to the Get API Key page
4290	Rate limited	Prompt to retry later or upgrade the plan
5000	Internal server error	Generic error card with a retry button

Rate limits & usage

The free tier includes 100 requests per day. Paid plans are billed by actual character usage — see Pricing. Usage for the current billing period is returned in every response under usage.

Embed with one line of code

Quick embed

<script src="https://cdn.chinesekey.org/peek.js"
        data-key="pk_live_..."
        data-density="minimal"></script>

Once loaded, hovering (or tapping, on touch devices) any Chinese character on the page reveals its structure card. The API and widget share the same usage quota.

Configuration

Attribute	Values	Default
data-key	your API key	required
data-density	minimal / full	minimal

FAQ

Does the widget affect page performance? The script targets under 15KB gzipped, with card styles inlined so it never leaks into your page's own CSS.

Is the same character always the same result? Yes — results are cached, so a given character always returns the same answer and can be served from an edge cache.

Use as an AI Tool

HanziPeek can be registered as a function/tool with common LLM providers. When a user asks about a character's structure, the model calls the tool and grounds its answer in verifiable, confidence-scored data instead of guessing.

OpenAI & Claude examples

{
  "name": "decompose_hanzi",
  "description": "Get the structural decomposition of a Chinese character or word: semantic/phonetic components, structure type, and word formation.",
  "parameters": {
    "type": "object",
    "properties": {
      "chars": { "type": "string", "description": "A Chinese character or word" },
      "lang": { "type": "string", "enum": ["zh", "en"] }
    },
    "required": ["chars"]
  }
}

This same JSON schema works as an OpenAI function definition or an Anthropic tool definition — pass it in your tools array and call api.chinesekey.org/v1/decompose when the model invokes it.

Best Practices

Confidence handling

Every result carries a confidence score. Don't hide low-confidence results — surface them, but keep the accompanying explanation appropriately conservative. If a field is unknown, the API returns null; never fill it with placeholder content.

Caching

The same character always returns the same answer, so results are safe to cache client-side or at the CDN edge. Batch multiple characters into a single request rather than issuing one call per character.

Error handling

Match the UI state to the response: a legitimate Chinese character with no data should render as "not in this dataset," not as an error. Reserve the error state for invalid input, invalid keys, and rate limits.

Changelog

Version	Notes
2026.08	Public documentation and widget release for chinesekey.org.