app/api/ 아래의 Next.js API 라우트에 있습니다. 프런트엔드는 이 라우트를 통해 모델 제공업체를 호출하고, 서버는 키 주입, API 주소 선택, 요청 매개변수 조정을 담당합니다.
이 라우트는 앱 내부 API로 주로 프런트엔드에서 사용하며, 매개변수는 버전에 따라 바뀔 수 있습니다. 다른 프로그램에서 호출하려면 저장소의 소스 코드를 기준으로 하세요.
공통 규칙
요청 헤더
공통 매개변수
모델 관련 라우트는 모두 다음 매개변수를 받습니다.접속 인증
CODE를 설정하면 /api/auth와 /api/umami/script를 제외한 모든 라우트는 요청에 유효한 ja_session Cookie가 있어야 하며, 없으면 다음을 반환합니다.
오류 형식
오류가 발생하면 라우트는 해당 HTTP 상태 코드와 통일된 형식의 오류를 반환합니다.message는 항상 간체 중국어 원문이며X-App-Locale의 영향을 받지 않습니다. 프런트엔드가 알려진 오류를 화면 언어로 번역해 표시합니다.- 모델 제공업체가 반환한 원본 오류 메시지는 그대로 전달되며, 프런트엔드가 번역하지 않습니다.
- 모델 제공업체의 응답이 60초를 넘으면 스트리밍이 아닌 요청은
504와 「上游接口请求超时，请稍后重试。」를 반환합니다.
스트리밍 응답
스트리밍 출력을 켜면 라우트는 상위 API의 OpenAI 호환 Server-Sent Events 스트림을 그대로 전달하며,Content-Type은 text/event-stream입니다. 끄면 상위 API의 전체 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은 일본 시간 자정까지 유효합니다. 서버에 사용 가능한 키가 없거나 생성에 실패하면 503을 반환하고, 프런트엔드는 내장된 예비 문장을 사용합니다.
/api/auth
GET:{ "requiresAuth": boolean, "authenticated": boolean }을 반환합니다.POST: 요청 본문은{ "password": "..." }입니다. 비밀번호가 맞으면{ "success": true }를 반환하고 세션 Cookie를 기록하며, 틀리면401을 반환합니다.