Skip to main content
應用程式的伺服器端邏輯都位於 app/api/ 下的 Next.js API 路由中。前端透過這些路由呼叫模型服務商，伺服器端則負責注入 Key、選擇介面位址和調整請求參數。
這些路由是應用程式的內部介面，主要供前端使用，參數可能隨版本變動。如果你要在其他程式中呼叫，請以儲存庫中的原始碼為準。

​
通用慣例

​
請求標頭

​
通用參數

與模型相關的路由都接受以下參數：
請求本文中不能包含 apiUrl。伺服器端會傳回 400，並提示「客户端不再支持自定义 API URL，请在服务器环境变量中配置上游端点。」介面位址只能透過 DEEPSEEK_API_URL 或 GEMINI_API_URL 設定。

​
存取驗證

設定了 CODE 時，除了 /api/auth 和 /api/umami/script 以外，其他路由都要求請求帶有有效的 ja_session Cookie，否則會傳回：

​
錯誤格式

發生錯誤時，路由會傳回對應的 HTTP 狀態碼和統一格式的錯誤：
  • message 一律是簡體中文原文，不受 X-App-Locale 影響。前端會把已知的錯誤訊息翻譯成目前的介面語言後再顯示。
  • 模型服務商傳回的原始錯誤訊息會原樣轉送，前端不會翻譯。
  • 等待模型服務商超過 60 秒時，非串流請求會傳回 504 和「上游接口请求超时，请稍后重试。」

​
串流回應

開啟串流輸出時，路由會直接轉送上游的 OpenAI 相容 Server-Sent Events 串流，Content-Type 為 text/event-stream。關閉時，則傳回上游的完整 JSON 回應。 串流輸出超過 90 秒沒有新資料時，伺服器端會在串流中送出一則錯誤事件，然後結束連線：

​
路由清單

​
POST /api/analyze

模型會傳回形如 {"tokens": [{"word", "pos", "furigana"}]} 的結構化 JSON。

​
POST /api/translate

譯文語言由 X-App-Locale 決定，並保留原文的段落和換行結構。

​
POST /api/word-detail

單字詳解會傳回 chineseTranslation、dictionaryForm、explanation、conjugation、example、exampleTranslation、pos 和 furigana 欄位。短語詳解會另外傳回 category 和 breakdown。

​
POST /api/image-to-text

​
POST /api/chat

伺服器端會在訊息清單前加入日語學習助手的系統提示詞。

​
POST /api/tts

成功時會傳回 Base64 編碼的音訊：

​
GET /api/daily-sentence

傳回當天（日本時間）的今日一句，包含 date、text、tokens 和四種語言的 translation。回應的 Cache-Control 有效期限到日本時間午夜零時。伺服器沒有可用的 Key 或產生失敗時會傳回 503，前端則改用內建備用句。

​
/api/auth

  • GET：傳回 { "requiresAuth": boolean, "authenticated": boolean }。
  • POST：請求本文為 { "password": "..." }。密碼正確時傳回 { "success": true } 並寫入工作階段 Cookie，錯誤時傳回 401。