API 接口路徑
Endpoint 就是一個 HTTP method 加 URL 路徑，例如 POST /v1/pronounce。瀏覽器使用已登入的 session；script、CLI 與 App 則送出 Authorization: Bearer API_KEY。登入用戶可在首頁 Settings 生成逐把限權、可撤銷的 personal key。版本化 schema 可從 GET /openapi.json 取得，亦隨 source 與 wheel 發佈；互動 docs 只在非 production 環境開啟。
GET/
給人使用的發音與 feedback 頁面。
POST/v1/pronounce
精簡 JSON：neutral canonical IPA、短解釋與警告。語體變體必須明確 opt in，目前不作為產品預設。
POST/v1/analyze
分析一個不超過 500 字元的句子或 clause，回傳完整可追溯結果。
POST/v1/analyze-batch
接受不超過 4,000 字元的段落；先按句子、必要時再按 clause 切成獨立 analyses，並保留原文 offsets。
POST/v1/research
法語限定、明確觸發的外部模型覆核；呼叫此 endpoint 會把文字送交畫面中標示的外部模型供應商。research:use 是 analysis:read 的上位權限，舊 key 保持相容；結果只作人工覆核建議，絕不自動改動 canonical 讀音。
POST/v1/trial/analyze
法語 Product Shell 的同源匿名預覽；固定為 neutral、受每日小額度限制，不寫入 History、帳戶用量或 audit archive。世界語 Public Beta 使用獨立的 /v1/trial/analyze/eo，不擴張既有法語 contract。
POST/v1/feedback
寫入已同意的修正。紀錄初始狀態是 provisional，不會自動改動發音引擎。
GET/v1/voices?backend_id=…
列出指定 backend 的安全 voice projection；瀏覽器不會取得供應商 API key。
GET/v1/tts/backends
列出 ElevenLabs v3 與 eSpeak NG 的可用狀態、成本類型、controls 及真實 input contract；不把概率式 IPA hint 說成可驗證的結構化音素輸入。
POST/v1/speech
以明確的 backend_id、intent 與 input_contract 朗讀最多 4,000 字元。ElevenLabs 是 hosted metered；eSpeak NG 是免費的 deterministic local text G2P，並回傳 WAV。
POST/v1/speech/phonemes
只接受版本化 Elparolo 音素 IDs 與指定 inventory；目前由 fail-closed 法語 eSpeak adapter 處理，未知符號會在合成前拒絕，不接受自由 IPA 字串。
POST/v1/trial/speech · /v1/trial/speech/phonemes
完成同源匿名分析後可用的免費 eSpeak 試聽；受每訪客、全站與併發限制，不能選 ElevenLabs。
GET/v1/version
回傳 engine、詞典、規則與 NLP 版本，方便將 feedback 對應到正確版本。
GET/v1/capabilities
免登入的版本化服務能力文件；列出已安裝分析語言、產品成熟度、Web／訪客／History 可用性、獨立審校狀態與相關 API links。已編譯的 engine 不會因此被自動當成正式產品。
GET/openapi.json
Public API v1 的正式 JSON Schema / OpenAPI contract。
GET · PUT/v1/me/preferences
讀寫已驗證帳戶的 History、介面與語音偏好。Personal API keys 與 owner 共用 subject，但不能管理帳戶狀態。
GET · PUT/v1/me/improvement-preference
獨立讀寫 Alpha 改進計畫選擇；與已發布的通用偏好 contract 分開，關閉後立即撤回候選存取。
GET/v1/me/usage
回傳目前帳戶的月度服務 credits。分析每 100 個字元向上取整為 1 credit；本地 eSpeak 目前不扣額；ElevenLabs 每個字元 1 credit。這是 Elparolo Product Shell allowance，不冒充供應商帳單。
GET · DELETE/v1/me/history
登入用戶可列出或清除預設開啟、可隨時關閉的分析歷史；也可用 DELETE /v1/me/history/{id} 刪除單筆。Personal key 的分析可進入 owner 歷史，但 key 本身不能讀取。服務另存不含全文的 hashes、IDs 與版本作為 operational audit metadata。
GET/v1/me/history/insights
從仍保留、可刪除的 History 即時計算教學現象足跡；不另建不可刪除的學習檔案。
GET · POST · DELETE/v1/account/api-keys
列出、生成與撤銷目前帳戶的 personal keys。這組路徑只接受可信的 browser session，不接受 Bearer key。
GET · POST · PATCH/v1/admin/…
只接受配置的 admin group；提供小型全站統計、每用戶 allowance/status 與 feedback/proposal 人工審批，不繞過 review store 的狀態轉移。
GET/v1/admin/improvement/candidates
按目前帳戶偏好即時讀取可撤回、去除帳戶身份並按推理版本去重的 History 候選。供有上限的離線 LLM 第二意見與人工評測使用；不會直接改寫引擎。
GET/health/ready
不需 API key；確認 runtime dependencies 可用，並回傳目前的 engine、詞典、規則與 NLP 版本，供部署核對及容器 readiness probe 使用。
GET/healthz
不需 API key；保留給相容性與基本 liveness 檢查。
GET/metrics
Prometheus 格式 operational metrics；production 必須使用獨立 Bearer token。
最小分析請求：
curl -H "Authorization: Bearer $ELPAROLO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"les amis","include_variants":false}' \
https://YOUR_HOST/v1/pronounce
← 回到發音頁面