memo-api

MaiMemo Open API

认证与基础信息

• 基础 URL：https://open.maimemo.com/open/api/v1
• Token：环境变量 $MAIMEMO_TOKEN — 可通过以下任一方式获取：
  • 应用：墨墨背单词 → 开放 API
  • 网页：打开 https://open.maimemo.com/open/api/v1/tokens/openapi，登录 MaiMemo 账号，请用户复制 Token 并粘贴回来，然后将其设为 $MAIMEMO_TOKEN
• Token 过期时间：从网页获取的 Token 有效期为 7 天。如果 API 调用提示 Token 已过期或无效（例如认证失败），请告知用户重新登录网页、复制并粘贴 Token，然后更新 $MAIMEMO_TOKEN。
• 认证标头：Authorization: Bearer $MAIMEMO_TOKEN

curl -s -X ${METHOD} "${BASE}/${PATH}" \
  -H "Authorization: Bearer $MAIMEMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '${BODY}'

速率限制：20/10s、40/60s、2000/5h

关键概念

• voc_id 解析：大多数端点需要 voc_id，而不是拼写。通过 GET /vocabulary?spelling=word 或 POST /vocabulary/query（单次最多 1000 个）进行解析。
• 使用 POST 更新：更新端点使用 POST /resource/{id}，而非 PUT/PATCH。
• 状态值：资源使用状态枚举（PUBLISHED、UNPUBLISHED、DELETED），具体取值因领域而异。
• 时间戳：所有时间均为 ISO 8601 格式。学习日期筛选使用北京时间（UTC+8）。

领域路由

任务	阅读参考文件
查询 voc_id / spelling → id	vocabulary-api.md
对自定义释义进行增删改查	interpretations-api.md
对助记内容进行增删改查（联想/谐音/派生/词根/词源/固搭/语法/对比等）	notes-api.md
管理单词列表 / 云笔记本	notepads-api.md
对例句进行增删改查	phrases-api.md
学习进度、记录、计划	study-api.md

调用任何端点前，请阅读相应的参考文件，了解准确的参数、请求体架构和 curl 示例。

学习使用场景

所有学习端点均使用 POST，且为 beta（需要打开自动同步）。

今日进度

端点：POST /study/get_study_progress（空请求体） 返回：finished（已完成数量）、total（目标数量）、study_time（毫秒）

场景	端点	关键参数
今日剩余单词	get_study_progress	计算 total - finished
今日学习时间	get_study_progress	study_time（毫秒 → 分钟）

今日单词

端点：POST /study/get_today_items

场景	端点	关键参数
今日遗忘的单词	get_today_items	is_finished: true，筛选 first_response = "FORGET"
今日新单词	get_today_items	is_new: true
未完成的单词	get_today_items	is_finished: false
指定单词的历史记录	get_today_items	spellings: ["word"] 或 voc_ids: ["id"]

学习记录

端点：POST /study/query_study_records

场景	端点	关键参数
未来 N 天内到期的单词	query_study_records	next_study_date.end: "YYYY-MM-DDT00:00:00+08:00"，as_count: true
计划中的单词总数	query_study_records	as_count: true（不设筛选条件）
经常遗忘的单词（顽固词）	query_study_records	遍历分页，筛选 tags = "STICKING"
熟记的单词	query_study_records	遍历分页，筛选 tags = "WELL_FAMILIAR"
导出所有学习数据	query_study_records	通过滑动 next_study_date 窗口进行分页，limit: 1000

添加单词

端点：POST /study/add_words

场景	端点	关键参数
将单词添加到计划	add_words	words: [{"id": "voc_id"}]，最多 1000 个
添加并提前复习	add_words	advance: true（也会立即触发复习，不受等级限制）

提前复习

端点：POST /study/advance_study

场景	端点	关键参数
提前复习单词	advance_study	voc_ids: ["voc_id1", ...]，最多 1000 个
需要达到 10 级或以上才能解锁提前复习功能

多领域工作流提示

• 为单词添加记忆口诀：词汇（获取 voc_id）→ 笔记（创建）
• 添加例句：词汇（获取 voc_id）→ 短语（创建）
• 添加自定义释义：词汇（获取 voc_id）→ 解读（创建）
• 根据学习数据生成词表：学习记录（查询）→ 记事本（创建并填写拼写）
• 获取完整单词信息：词汇（获取 voc_id）→ 解读 + 笔记 + 短语（全部列出）