Dev Spec v2 · ← 返回文档首页

03 接口规格

前缀 /api/tt/v1；匿名用户通过 X-Anon-Id 识别，可以玩免费集，注册后进度合并。

1. 内容

方法 路径 说明
GET /seasons?lang=ja 季列表：封面、简介、集数、免费集数、是否已解锁
GET /seasons/{id}/episodes 集列表：标题、时长、完成状态、是否锁定
GET /episodes/{id} 剧本（已按用户的记忆和剧情变量替换占位符）+ 资源链接；未解锁返回 LOCKED 和购买选项
POST /episodes/{id}/progress {"node_id":"n5","vars":{"bag":true}}（前端在节点切换时上报）
POST /episodes/{id}/complete {"rating":4,"feedback":"可选的一句话"} → 返回本集总结（词汇、得分、下集预告）

2. 口语关卡

POST /episodes/{id}/checkpoints/{node_id}（multipart：音频 + kind + attempt_no）

// 返回（跟读）
{"passed": true, "score": 78, "words": [{"w":"袋","score":52,"issue":"pitch accent"}], "next": "n3"}
// 返回（选择）
{"matched_option": 0, "confidence": 0.82, "next": "n4a"}
// 返回（自由回答）
{"understood": true, "reply_text": "映画いいね！", "reply_audio_stream": "/api/tt/v1/stream/abc",
 "correction": {...}, "next": "n6"}

GET /episodes/{id}/checkpoints/{node_id}/hint?level=1|2 → 提示内容。

3. 记忆与学习

方法 路径 说明
GET /me/memories 查看记忆
DELETE /me/memories/{id} 删除一条；DELETE /me/memories 全部删除
GET /me/vocab 词汇本（带复习时间）
POST /me/vocab/review 复习结果
GET /me/stats 连续打卡、周报

4. 角色消息与自由对话（P2）

方法 路径 说明
GET /messages 收到的角色消息
POST /messages/{id}/reply 语音回复（按自由回答处理）
POST /freetalk/sessions {"character_id":"yuki"} → 会话 ID；无 Pro 权益返回 PRO_REQUIRED
POST /freetalk/sessions/{id}/turns 语音一轮；超出每日时长返回 FAIR_USE_LIMIT

5. 安全

方法 路径 说明
POST /me/age {"birth_year": 2001}
POST /me/session-heartbeat 前端每分钟上报一次，服务器判断是否需要休息提醒

危机处理不是单独的接口：关卡或自由对话返回 {"safety": {"action":"pause","resources":[...]}} 时，前端必须暂停剧情并显示求助资源。

6. 后台 /api/tt/admin/v1

路径 说明
POST /seasons {"theme":"...","lang":"ja","level":"beginner","region":"global"} → 启动流水线
GET /seasons/{id}/pipeline 各集各步骤的进度与质检结果
GET /episodes/{id}/health 评分、完成率、各节点退出率、关卡求助率
POST /episodes/{id}/regenerate 手动触发重新生成（一般由定时任务自动触发）
GET /stats/daily 次日留存、完成率、转化率、每集可变成本、内容成本
本文档由 01_陪练_开发spec/03_接口规格.md 生成 · 2026-09-27 · 打印可用 Ctrl/Cmd+P 另存为 PDF