# Cheongmyeong (청명) — game sound matching API
> Find sounds in your own SFX library by describing them. Works in any major language.

Auth: X-API-Key header. Get a free key: POST /signup {"email": "you@example.com"}
Machine-readable spec: /openapi.json · Interactive docs: /docs

## Core endpoints
- POST /match {"query": "...", "top_k": 5} → candidates with file_path (local path on the
  user's machine), caption (what the AI heard), duration_sec, preview_url, score.
  `normalized_query` shows how the words were interpreted as an acoustic phrase — surface it
  so the user can catch misinterpretations.
- POST /axis {"query": "impact", "high": "heavy", "low": "light", "top_k": 8} — sort candidates
  along an intensity axis. Absolute queries cannot hear "small/weak" (measured 43% = worse than
  random); the contrast axis reaches 85–94%. Use /axis for any "more X / less X" request.
- GET /preview/{rid}?key=... — stream a 10s low-fi ogg preview for auditioning.
- POST /index/add_audio — register clips with client-computed vectors (see Indexing below).
- GET /index/list · POST /index/remove · GET /index/status — manage the index.
- GET /account — plan, quotas, usage.

## How to query well (measured)
- Describe the SOUND, not the game feature: "a bubbling poison hiss" beats "poison skill sound".
  Design terms are matched mostly via filenames — they work when the library is well-named.
- duration_sec is returned for every candidate: filter "a 3-second sting" yourself — free and exact.
- There is NO reranker for audio (rerank_status is always "not_applicable"): audio LMs showed
  position bias on stylized game SFX (measured). Embedding+caption+filename fusion is the ranking.
- match_quality is weakly calibrated for audio — prefer auditioning top-k over trusting "none".

## Indexing your library (one-time, on the user's machine)
- Captions are generated locally by a 7B audio model — this needs the user's GPU (~6GB VRAM)
  and is why originals never leave their machine. Download the kit: /download/cheongmyeong_kit.zip
- Run: python indexer_audio.py --src <sound folder> --server <this host> --key <api key>
  It scans, captions (resumable cache), embeds (GLAP audio + caption, mexma filename), and
  uploads vectors + 10s previews in batches. Incremental — re-run after adding files.
- An agent can drive re-indexing (same command), but the first GPU setup is a human step.

## Plans (card checkout, instant activation)
- Free: 500 sounds indexed, unlimited search. Indie ($12/mo or $115/yr): 30,000 sounds.
  Studio (150k+, teams): inquiry form on the landing page.
- POST /billing/checkout {"plan": "indie-monthly"|"indie-annual", "email": "<signup email>"} → {"url"}
  Payment is a human action: open the URL for your user. Unlike HyeAn there is no caption
  metering — audio captions are generated on the user's own GPU at indexing time.

## Notes for agents
- Search runs on CPU and is fast; the multilingual query normalizer uses an LLM — after long idle
  the FIRST query may take longer or fall back to the raw query (filename channel still carries it).
- Quota errors (402/413/422 QUOTA_EXCEEDED) mean the plan cap — surface the upgrade, don't retry.
- Rate limits: /match 120/min per IP.

Brand: https://ai.14dimension.com · Contact: admin@14dimension.com · Sibling product (images): https://hyean.14dimension.com