# Clavis Sinica

> API for decomposing Chinese text — idioms, sentences, passages, classical
> Chinese, and full lesson breakdowns — into structured, sourced results.
> Lookup fields trace to a specific table/column in an 11,114-entry classical
> Chinese dictionary; generative fields (produced by an LLM) are explicitly
> labeled as such and never mixed in silently with dictionary lookups.

## Core concepts

- Single endpoint: `POST https://clavissinica.org/v1/chinese/run`
- Auth: `Authorization: Bearer ck-live_...` (get a key at /get-key, no card
  required — key issuance is a two-step email confirmation: POST /v1/keys sends
  a one-click link, the key is revealed only after clicking it)
- Billing: prepaid ckTok balance, $1 = 100 ckTok, charged per call, refunded
  automatically on failure or not-found
- **Request shape: `{"service_code": "...", "payload": {...}}` works for every
  service code.** `{"input": "..."}` is a shorthand that only sets the primary
  field of single-field services — if you need any other parameter you must use
  `payload`. When in doubt, always use `payload`; there is no case where it
  fails and `input` succeeds.
- Field-level spec (names, types, length caps, enum values, required flags) is
  machine-readable at `GET /v1/chinese/services` — zero ckTok, any valid key.
  Read it at startup instead of hardcoding a local copy; it is generated from
  the same source the engine validates against.
- Every response includes `provenance: {type, generated_fields}` — `type` is
  "lookup" or "generative", `generated_fields` lists which top-level keys in
  `data` come from real-time LLM generation vs. deterministic dictionary lookup
- Optional `idempotency_key` (top level): the same key replays the first result
  without charging again
- Unknown top-level fields are ignored, and the response carries a `warnings`
  array saying which ones were dropped. Only `service_code`, `input`,
  `payload`, `idempotency_key` are accepted at the top level.
- Free unauthenticated demo: `POST /v1/demo/run`, same body shape, no key
  needed, rate-limited per IP, covers six of the nine service codes

## Async services

`decompose.lesson` and `decompose.wenyan_lesson` are **submit-then-poll**:
the call returns `task_id` immediately, then poll
`GET /v1/chinese/tasks/{task_id}` every few seconds until `status` is `done`
or `error`. Each takes roughly 45–90 seconds. The worker runs tasks serially.

## Rate limits

- Per account: 120 requests/minute
- Per account: at most 3 async tasks queued or running at once
- Global: at most 20 async tasks in the queue
- Exceeding any of these returns **HTTP 429** with `error: "rate_limited"`,
  a `scope` naming which limit was hit, and a `Retry-After` header.
  **Rejected requests are not charged.** Honour `Retry-After`; do not retry
  tight-loop.

## Errors

Machine-readable `error` code plus a human `msg`. Parameter errors also carry
`field` and `expected` so a client can render the right input control.

- `invalid_param` (400) — your parameters; `field` says which one
- `not_found` (404) — the endpoint works, the content is not in the dictionary
- `rate_limited` (429) — see above
- `payload_too_large` (413), `unsupported_media_type` (415)
- `upstream_error` (502) — timeout or connection failure; the engine was never
  reached. Nothing to do with your request — retrying is reasonable.
- `upstream_rejected` (502) — upstream returned a failure we cannot classify
- `upstream_unavailable` (503) — an upstream dependency is down; **retry this one**

Anything charged but not delivered is refunded automatically.

## Service codes

Nine codes. Prices and shapes below are a summary; the authoritative,
machine-readable version is `GET /v1/chinese/services`.

- `decompose.english_morph` — English word → prefix/root/suffix, root family,
  cross-lingual notes. Lookup. 8 ckTok. payload: `word`.
- `decompose.idiom` — Chinese idiom (成语) → meaning, example, source citation,
  optional six-part story. Returns both `*_zh` and `*_en` fields (the only
  service that does). Lookup. 10 ckTok. payload: `idiom`.
- `decompose.sentence` — Chinese sentence → tokens, pinyin, grammar
  explanation, per-word drill-down. The grammar explanation is **always in
  English**; it is not switchable. Generative. 15 ckTok. payload: `sentence`.
- `decompose.passage` — Chinese passage → readability verdict, new-word rate,
  priority words, grammar patterns with coverage counts. Lookup. 20 ckTok.
  payload: `text`, `target_level` (1–9, **HSK 3.0 level, not school grade**).
  Input over 3000 characters is truncated with an explicit `truncated` flag —
  when that flag is set, every metric reflects only the first 3000 characters.
- `decompose.wenyan` — Classical Chinese → per-character original meaning,
  Shuowen Jiezi citation, six-category classification, classical citations.
  Lookup. 12 ckTok. payload: `text`, `limit`. Coverage varies per character.
- `decompose.lesson` — Modern Chinese lesson text → seven-layer breakdown
  (chapter/sentences/vocab/characters/grammar/theme/exercises). Generative,
  **async**. 100 ckTok. payload: `text`, `title`, `grade`, `focus_chars`,
  `vocab_list`.
- `decompose.wenyan_lesson` — Same seven-layer breakdown for classical Chinese.
  Generative, **async**. 100 ckTok. payload: `text`, `title`, `grade`.
- `ocr.image` — Photo of Chinese text → recognised text. One image per call,
  billed per image; a ten-page textbook is ten calls. JPEG/PNG/WebP only (not
  HEIC), 6 MB cap on the base64 payload. Generative. 6 ckTok.
  payload: `image_base64`.
- `convert.script` — Simplified/Traditional conversion. Lookup. 2 ckTok.
  payload: `text`, `direction` (s2t/t2s/s2twp/tw2sp). Use s2twp (not s2t) for
  correct Taiwan vocabulary localisation, not just character-level conversion.

## Account management

- `GET /v1/account/balance`, `GET /v1/account/keys`,
  `POST /v1/account/keys/revoke`, `GET /v1/account/ledger`,
  `GET /v1/account/usage`, `POST /v1/account/topup` (all require Bearer auth)

## Machine-readable references

- Integration guide (start here): https://clavissinica.org/guide.html
- OpenAPI spec: https://clavissinica.org/openapi.json
- Live service catalogue: `GET /v1/chinese/services` (needs a key, costs nothing)
- Prose docs with real request/response examples: https://clavissinica.org/docs
- Embeddable widget (no key needed): https://clavissinica.org/clavis-widget.js

## Official clients

- Python: `pip install clavis-sinica` — https://pypi.org/project/clavis-sinica/
- Node/TypeScript: `npm install @clavis-sinica-org/sdk` —
  https://www.npmjs.com/package/@clavis-sinica-org/sdk

The two registries use different naming conventions (PyPI has no scopes); it is
the same API and the same behaviour. Both clients fetch the field spec from
`GET /v1/chinese/services` at startup, honour `Retry-After` on 429, back off on
502/503, poll async services to completion, and surface the `warnings` array.
Calling the HTTP API directly is equally supported — there is nothing the
clients do that you cannot do with plain `fetch` or `requests`.

## Legal

- Privacy policy: https://clavissinica.org/privacy
- Terms of service: https://clavissinica.org/terms
- Operator: Clavis Sinica Limited, NZBN 9429047957282, Auckland, New Zealand — johnchu@silink.ai

## Not in scope

- Hanzi (single character) and Chinese vocabulary decomposition are **not**
  offered here — that's the sister product chinesekey.org (separate pricing,
  separate `pk_live_` keys, not interchangeable with this API).