How do I get an API key?

Two options. (1) For full management — create keys, view usage, revoke — sign up at the API Console and generate one from /dashboard. (2) For instant access without an account, call POST /v1/auth/register with your email and a free-tier key is handed back immediately. No credit card for either path.

Is the API really free?

Yes — the character lookup, pinyin, HSK list, and grammar endpoints are free forever with a soft daily quota. Larger tools (grammar checker, reading level, sentence generator) use the same free tier with a smaller daily cap.

Can I use the API in production?

Yes. The free tier is for prototypes, learning projects, and personal sites. For commercial traffic, the pro tier raises the daily cap 100x and removes the Chinese365 attribution.

What language is the data?

pinyin uses ISO-style tone marks (nǐhǎo). JSON keys are stable English identifiers. Content includes both English meanings and Chinese examples.

§ Developer · API

The same Chinese intelligence over HTTP.

Programmatic access to the same structured Knowledge Base that powers every tool on chinese365.org. Built for developers, schools, content platforms, and the perpetually curious.

Get an API key Read the auth model OpenAPI 3.0 spec

§ 01 — Quick Start

60 seconds from zero to your first response.

Step 01

Register

curl -X POST https://chinese365.org/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

Returns: { "key": "c365_free_...", "tier": "free" }

Step 02

Call an API

curl https://chinese365.org/v1/character/学 \
  -H "Authorization: Bearer c365_free_..."

Every endpoint accepts the API key as either Authorization or X-API-Key.

Step 03

Watch your quota

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1714824000

Three rate-limit headers on every response. 429 also includes Retry-After.

Want to manage keys instead of calling the register endpoint?

Open API Console →

§ 02 — Base URL

One URL, all endpoints.

TLS 1.3. JSON over HTTPS. No SDK required — any language with an HTTP client works.

https://chinese365.org/v1

§ 03 — Authentication

Two header styles, same key.

Authorization: Bearer

The HTTP-standard way. Works with every HTTP client.

Authorization: Bearer c365_free_xxxx

X-API-Key header

Convenient when your gateway or proxy rewrites Authorization.

X-API-Key: c365_free_xxxx

Keys follow the shape c365_<tier>_<32-char-token>. The tier prefix is free, starter, growth, pro, or business.

§ 04 — Endpoints

9 endpoints, one knowledge base.

4 free · 2 starter · 3 growth

POST/v1/auth/registerfree

POST { email: "dev@example.com" }

Try it in the UI →

GET/v1/character/{char}free

Look up a single Chinese character — pinyin, meaning, stroke, components, HSK level.

GET /v1/character/学

Try it in the UI →

GET/v1/pinyin?text=…free

Convert Chinese text to pinyin. Browser-class: tone marks, numeric tones, or none.

GET /v1/pinyin?text=我喜欢学习中文&style=marks

Try it in the UI →

GET/v1/hsk/{level}free

Get all words for an HSK level (1–9).

GET /v1/hsk/1

Try it in the UI →

POST/v1/sentence/analyzestarter

Analyze a sentence: tokens, grammar, HSK level, difficulty, translation. (LLM)

POST { text: "我昨天去了北京。" }

Try it in the UI →

POST/v1/grammar/checkstarter

Find grammar errors with explanations. (LLM)

POST { text: "我很喜欢吃了中国菜。", learnerLevel: "HSK 2" }

Try it in the UI →

POST/v1/reading/analyzegrowth

Estimate reading level + optional rewrite to a target HSK level. (LLM)

POST { text: "...", rewriteTo: 3 }

Try it in the UI →

POST/v1/sentence/generategrowth

Generate example sentences at a target HSK level. (LLM)

POST { word: "学", hskLevel: 2, count: 5 }

Try it in the UI →

POST/v1/text/simplifygrowth

Rewrite text at a specific HSK level. (LLM)

POST { text: "...", targetLevel: 3 }

Try it in the UI →

§ 05 — Rate limits

Pick a tier. Cancel anytime.

Each plan has a per-minute ceiling and a daily quota. Higher tiers unlock LLM endpoints. Counts are enforced at the edge in Redis.

Plan

Daily quota

Rate limit

Price

Key prefix

FreeDefault

1,000

10/min

c365_free_xxx

Starter

50,000

100/min

c365_starter_xxx

Growth

250,000

500/min

$29

c365_growth_xxx

Pro

1,000,000

2,000/min

$99

c365_pro_xxx

Business

5,000,000

10,000/min

$299

c365_business_xxx

§ 06 — Error codes

Same shape on every endpoint.

HTTP

Code

Description

400

INVALID_REQUEST

Bad parameters or malformed JSON body.

401

UNAUTHORIZED

Missing or invalid API key.

403

FORBIDDEN

Key tier does not allow this endpoint.

404

NOT_FOUND

Resource not found in the Knowledge Base.

429

RATE_LIMITED

Rate limit or daily quota exceeded.

503

LLM_UNAVAILABLE

All AI providers down.

500

INTERNAL

Server error.

§ 07 — AI provider chain

Fallback ladder, Redis cache in front.

LLM-assisted endpoints call providers in order. Each response is hashed and cached in Redis, so repeat traffic costs nothing and survives provider outages.

minimaxPrimaryDeepSeek-V3Qwen-PlusGPT-4o-miniRule engineFallback

Cached responses return in < 5 ms. Cache TTL is unbounded — we never expire LLM output that has already served a request.

§ 08 — Same data, two interfaces

Every API has a web twin.

The website tools and the API read from the same Knowledge Base and the same code paths. Whichever way you call us, you get the same answer. Use the web tools to explore; reach for the API when you need to ship.

API

Web tool

Notes

/v1/pinyin

Pinyin Converter →

Runs locally in your browser, no upload.

/v1/character

Character Decomposer →

Runs locally in your browser, no upload.

/v1/sentence/analyze

Sentence Analyzer →

LLM-assisted, cached.