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。