Lingara API 參考文件

錯誤

402application/json

一個按用量收費嘅用戶端嘅呼叫，喺佢用任何嘢之前已經被拒絕。spend_cap_reached：用戶端或者佢嘅帳戶已經到咗每月嘅支出上限；請喺整合頁面調高上限。metered_billing_inactive：呢個帳戶嘅按用量收費未啟用；請喺整合頁面設定，或者更新付款方式。

410application/json

回應呢個請求所用嘅 API 版本已經停用。請喺 Lingara-Version 傳一個有支援嘅版本，或者將用戶端綁去另一個版本。

4XXapplication/json

請求被拒絕。code 講出原因，error 用文字解釋。

503application/json · text/plain

服務暫時用唔到；請等 Retry-After 入面嘅秒數之後再試。維護期間，回應內容係純文字，而唔係錯誤封包。

5XXapplication/json

請求被拒絕。code 講出原因，error 用文字解釋。

codestring必填

請求被拒絕嘅原因，係一個穩定嘅代碼，可以用嚟做分支處理：例如 insufficient_scope（403）、rate_limited（429），對按用量收費嘅用戶端仲有 spend_cap_reached（402）同 metered_billing_inactive（402）。

errorstring必填

詞彙

按學習者嘅程度生成詞彙表。

• 生成詞彙表 POST /v1/vocab/stream

課程計劃

建立課程計劃、讀取課程計劃，同埋重新連接去仲生成緊嘅計劃。

• 建立課程計劃 POST /v1/lesson-plans
• 攞課程計劃 GET /v1/lesson-plans/{id}
• 重新連接去課程計劃 GET /v1/lesson-plans/{id}/stream

導師

同語言導師一輪一輪噉傾偈。

• 傳送一輪導師對話 POST /v1/tutor/message

事件

讀你帳戶入面發生嘅事件，一頁一頁噉讀，或者用串流。

• 列出事件 GET /v1/events
• 傳送事件 POST /v1/events
• 串流事件 GET /v1/events/stream

帳戶

睇吓你仲剩幾多額度。

• 攞你剩餘嘅額度 GET /v1/usage

參考

呢份文件嘅機器可讀版本。

• 攞呢份文件 GET /v1/openapi.json
• 攞事件文件 GET /v1/asyncapi.json
• 列出 API 版本 GET /v1/versions
• 攞一個 API 版本 GET /v1/versions/{id}

事件目錄

Lingara 會將你帳戶啲課程計劃同用量發生嘅事記錄做事件，亦都會接收你嘅遊戲或者應用程式送嚟嘅事件。每個事件，無論點樣傳送，都用同一種封包，事件目錄列晒全部事件。 Webhook 同事件

• Lingara → 你 lesson_plan.ready
• Lingara → 你 lesson_plan.failed
• Lingara → 你 usage.threshold_reached
• Lingara → 你 webhook.test
• Lingara → 你 app.installed
• Lingara → 你 app.uninstalled

• 你 → Lingara world.context_changed
• 你 → Lingara world.practice_requested