English Reading API Reference
考研英语每日阅读系统的完整 API 文档。包含文章、词典、背单词、音频等全部端点。
🔐 Authentication#
认证通过 Bearer Token 或 Cookie 传递。
公开端点：词典查询、文章阅读、音频播放、翻译 — 无需认证。
需登录端点：提交答案、背单词、收藏、统计等。
Authorization: Bearer <TOKEN>
Base URL: https://tools.getuphole.top/english-reading
Token 通过 /api/auth/login 获取，有效期 24 小时。Cookie 名称：auth_token。
📰 Articles#
每日考研英语阅读文章的获取与交互。
获取文章列表，支持分页。
| Name | Type | Description |
|---|---|---|
| page optional | int | 页码，默认 1 |
| per_page optional | int | 每页数量，默认 20 |
curl https://tools.getuphole.top/english-reading/api/articles?page=1
获取今日文章，含完整段落、题目和生词注释。若今日未发布则回退到最新文章。
curl https://tools.getuphole.top/english-reading/api/articles/today
获取指定文章详情，包含所有段落、题目和词汇注释。
curl https://tools.getuphole.top/english-reading/api/articles/5
下载文章 PDF 版本（含段落翻译和题目）。自动生成并缓存。
curl -O https://tools.getuphole.top/english-reading/api/articles/5/pdf
提交文章阅读理解答案，返回评分和解析。
| Name | Type | Description |
|---|---|---|
| answers required | object | {question_id: selected_option} |
| is_redo optional | bool | 是否重新作答 |
curl -X POST .../api/articles/5/submit \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{"answers":{"1":"B","2":"D","3":"A","4":"C"}}'重置文章答题状态，允许重新作答。
curl -X POST .../api/articles/5/reset \ -H "Authorization: Bearer <TOKEN>"
📖 Dictionary#
查词服务。自动识别比较级/最高级、支持牛津词典回退和拼写纠错。
查词（简化版） — 自动识别比较级（higher→更+高）、最高级（biggest→最+大），词干还原，牛津回退。
响应含 audio_url（牛津原声或 TTS）、inflection（comparative/superlative）、stem_match 等字段。
curl https://tools.getuphole.top/english-reading/api/dictionary/higher
# → {"word":"high","definition":"a. 更高的...","inflection":"comparative","audio_url":"..."}词库完整信息。登录后返回学习状态和收藏标记。
模糊搜索，支持拼写纠错。?q=&limit=20
MiMo AI 翻译（英→中）。{"text":"..."}，≤500 字符。
🔊 Audio#
单词发音与段落朗读，自动缓存。
单词 TTS 发音（Google TTS）。首次生成后缓存，后续毫秒级响应。若牛津词典有该词发音，前端应优先使用 /api/audio-proxy。
curl https://tools.getuphole.top/english-reading/api/tts/algorithm -o word.mp3
🆕 段落朗读 — 生成整段文章的 TTS 音频。按内容 hash 缓存，段落变更自动重新生成。首次需等待数秒（依赖段落长度），缓存后 <5ms 响应。
| Name | Type | Description |
|---|---|---|
| article_id required | int | 文章 ID |
| order_num required | int | 段落编号（从 1 开始） |
# 播放文章 5 的第 1 段 curl https://tools.getuphole.top/english-reading/api/tts/paragraph/5/1 -o para.mp3
牛津词典原声音频代理。绕过 CORS，支持前端 <audio> 直接播放。?url=<oxford_audio_url>
<audio src="/english-reading/api/audio-proxy?url=..." controls></audio>
📚 Vocabulary#
SM-2 间隔重复背单词系统。均需认证。
今日待复习单词（SM-2 算法排序）。
标记复习结果。{"word":"...","correct":true}
学习进度统计。
额外推荐单词。?count=20
GET 获取 / POST 修改学习设置。
每日打卡。{"duration_seconds":300}
今日打卡状态。
📋 Word Books#
自定义单词本管理。均需认证。
获取所有单词本（含进度统计）。
创建单词本。{"name":"红宝书"}
编辑单词本。
删除单词本。
学习模式。?count=20
单词列表（分页|排序|搜索）。?page=&limit=&sort=&search=
添加单词。{"word":"..."} 或批量 {"words":["...","..."]}
移除单词。?word=xxx
⭐ Favorites#
收藏单词管理。均需认证。
收藏列表（含学习状态）。
收藏单词。{"word":"ephemeral"}
取消收藏。?word=xxx
⏱️ Reading Sessions#
阅读会话追踪。均需认证。
开始阅读。{"article_id":5}
结束会话。{"duration_seconds":180}
📊 Statistics#
学习数据统计。均需认证。
综合学习统计（正确率、学习天数、词汇量等）。
阅读历史（分页）。
打卡日历。?year=&month=