匿词 API Key 使用文档

匿词 API Key 用于把你的匿词仓库接入脚本、自动化工具或个人工作流。它只能访问 Key 所属用户自己的数据，不能访问其他用户，也不能操作登录、支付、会员、反馈、管理后台等非词库能力。

可以做什么

• 读取你的词书列表、词书详情、词书内单词列表。
• 创建、重命名、删除你的自定义词书。
• 给任意可写词书添加、编辑、移动、删除单词。
• 批量添加单词，或批量删除单词。
• 给单词添加、编辑、删除自定义释义。
• 给自定义释义添加或删除例句、自定义示例。
• 查询单词释义，给外部工具做展示或补全。

获取和使用 Key

在浏览器登录 https://neath.clingword.com，打开顶部导航栏的 API Key 页面创建、显示、复制或撤销 Key。Key 以 naklive 开头。

调用 /api/v1 接口时，推荐使用请求头：

X-Neath-API-Key: nak_live_xxx

也兼容 Bearer 写法：

Authorization: Bearer nak_live_xxx

下面的示例统一使用环境变量：

export NEATH_API_KEY="nak_live_xxx"
export NEATH_API_BASE="https://neath.clingword.com/api/v1"

权限和限制

默认创建的 Key 具备以下权限：

• library:read：读取词书、单词、当前用户 API 信息。
• library:write：创建、编辑、删除词书和单词，管理自定义释义和例句。
• dictionary:read：查询单词释义。

服务端会限制每个用户可保留的有效 Key 数量，并对 API 请求做防滥用限流。超过限制时返回 429 和 Retry-After。

基础交互逻辑

建议外部工具按这个顺序集成：

1. 调用 GET /me 确认 Key 有效，并拿到当前用户信息。
2. 调用 GET /notebooks 展示用户词书，或选择一个默认写入目标。
3. 调用词书、单词、释义和例句接口完成具体操作。
4. 收到 401 时提示用户更换或重新复制 Key。
5. 收到 403 时提示 Key 权限不足。
6. 收到 429 时读取 Retry-After，等待后重试。
7. 写操作成功后刷新相关列表，不要假设本地缓存仍然准确。

当前用户

请求

curl "$NEATH_API_BASE/me" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用途

用于启动时检查 Key 是否有效、显示当前账号和当前 Key 的基础信息。

常见响应

{
  "user_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "nickname": "LaoChou",
  "membership_type": "mix",
  "api_key": {
    "id": "nak_xxx",
    "name": "Raycast",
    "status": "active",
    "scopes": ["library:read", "library:write", "dictionary:read"]
  },
  "stats": {
    "total_words": 320,
    "total_notebooks": 5
  }
}

词书

获取词书列表

curl "$NEATH_API_BASE/notebooks" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用法：工具启动后拉取词书，给用户选择写入目标。

示例响应：

{
  "items": [
    {
      "id": 123,
      "name": "阅读生词",
      "description": "阅读时收集",
      "word_count": 18,
      "is_default": false,
      "is_system": false
    }
  ]
}

注意：词书列表字段名是 items，不是 notebooks。

创建词书

curl "$NEATH_API_BASE/notebooks" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "论文阅读",
    "description": "读 paper 时临时收集"
  }'

交互逻辑：创建成功后，把返回的 id 保存为后续添加单词的 notebook_id。

获取词书详情

curl "$NEATH_API_BASE/notebooks/123" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用法：打开词书详情页前拉取名称、描述、单词数量等信息。

重命名或修改描述

curl -X PATCH "$NEATH_API_BASE/notebooks/123" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "论文阅读 2026",
    "description": "精读和泛读材料"
  }'

交互逻辑：只允许修改属于当前用户的可写词书。系统词书不可写。

删除词书

curl -X DELETE "$NEATH_API_BASE/notebooks/123" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

交互逻辑：删除前应在你的工具里二次确认。默认词书、系统词书不可删除。

单词

获取所有单词

curl "$NEATH_API_BASE/words" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用法：做全局搜索、导出或本地缓存同步。

获取某个词书里的单词

curl "$NEATH_API_BASE/notebooks/123/words" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用法：打开某个词书时展示其单词列表。

添加单词

curl "$NEATH_API_BASE/notebooks/123/words" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "word": "pyramid",
    "sentence": "The pyramid is ancient.",
    "custom_meanings": [
      {
        "part_of_speech": "noun",
        "definition": "金字塔",
        "examples": [
          {
            "sentence": "A pyramid rises.",
            "translation": "一座金字塔耸立。"
          }
        ]
      }
    ]
  }'

交互逻辑：

• word 是必填。
• sentence 可选，适合保存原文上下文。
• custom_meanings 可选，适合从外部词典或用户输入同步自定义释义。
• 添加成功后返回新单词详情，工具应使用返回的 id 更新本地状态。
• 自定义释义不会作为顶层 custom_meanings 返回，而是落在 definition.meanings 中。

常见响应结构：

{
  "id": 456,
  "word": "pyramid",
  "sentence": "The pyramid is ancient.",
  "notebook_id": 123,
  "type": "user",
  "created_at": "2026-05-10T10:00:00",
  "definition": {
    "source": "user",
    "meanings": [
      {
        "id": "cm_xxx",
        "source": "user",
        "part_of_speech": "noun",
        "definition": "金字塔",
        "examples": [
          {
            "id": "ex_xxx",
            "source": "user",
            "sentence": "A pyramid rises.",
            "translation": "一座金字塔耸立。"
          }
        ]
      }
    ]
  }
}

获取单个单词详情

curl "$NEATH_API_BASE/words/456" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用法：用户点击单词时拉取完整释义、例句和所在词书。

释义数据统一在 definition.meanings 里。自定义释义和自定义例句会带 source: "user"，并带服务端生成的 id，后续编辑和删除要使用这些 ID。

编辑单词或移动词书

curl -X PATCH "$NEATH_API_BASE/words/456" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "word": "pyramidal",
    "sentence": "A pyramidal shape.",
    "notebook_id": 789
  }'

交互逻辑：

• 修改 word 会改变展示单词。
• 修改 sentence 会更新上下文句子。
• 传入 notebook_id 可以把单词移动到另一个属于当前用户的可写词书。

删除单个单词

curl -X DELETE "$NEATH_API_BASE/words/456" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

交互逻辑：删除前建议提示用户确认。删除后刷新当前词书列表。

批量操作

批量添加单词

curl "$NEATH_API_BASE/notebooks/123/words/bulk" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "words": [
      "alpha",
      "beta",
      {
        "word": "gamma",
        "sentence": "Gamma rays are energetic."
      }
    ],
    "skip_duplicates": true
  }'

交互逻辑：

• 一次最多 2000 个词条。
• 字符串会被当成单词。
• 对象可以带 word、sentence、custom_meanings。
• skip_duplicates: true 时跳过重复词；适合导入工具默认使用。
• 如果超过 2000 条，会返回 400，并且不会部分写入。

常见响应结构：

{
  "success_count": 2,
  "duplicate_count": 1,
  "failed_count": 0,
  "notebook_id": 123,
  "items": [
    {"word": "alpha", "status": "created", "word_id": 501},
    {"word": "beta", "status": "duplicate", "reason": "already_exists", "word_id": null}
  ]
}

批量删除指定单词

curl "$NEATH_API_BASE/words/delete" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "word_ids": [1, 2, 3]
  }'

按词书全选删除

curl "$NEATH_API_BASE/words/delete" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notebook_id": 123,
    "is_select_all": true,
    "excluded_ids": [2]
  }'

交互逻辑：适合列表页“全选后删除”。excluded_ids 表示全选后用户取消勾选的单词。

自定义释义

添加自定义释义

curl "$NEATH_API_BASE/words/456/custom-meanings" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "part_of_speech": "noun",
    "definition": "金字塔",
    "examples": []
  }'

交互逻辑：适合用户在外部工具中手动修正释义。成功后返回更新后的单词详情。

真实响应结构是 { "meaning": ..., "word": ... }。其中完整单词详情仍在 word.definition.meanings 中。

{
  "meaning": {
    "id": "cm_xxx",
    "source": "user",
    "part_of_speech": "noun",
    "definition": "金字塔",
    "examples": []
  },
  "word": {
    "id": 456,
    "word": "pyramid",
    "definition": {
      "meanings": []
    }
  }
}

编辑自定义释义

curl -X PATCH "$NEATH_API_BASE/words/456/custom-meanings/cm_xxx" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "part_of_speech": "noun",
    "definition": "金字塔；锥体结构"
  }'

真实响应结构同样是 { "meaning": ..., "word": ... }。

删除自定义释义

curl -X DELETE "$NEATH_API_BASE/words/456/custom-meanings/cm_xxx" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

交互逻辑：删除释义会同时移除挂在该释义下的自定义例句。

真实响应结构：

{
  "deleted": true,
  "meaning_id": "cm_xxx",
  "word": {
    "id": 456,
    "word": "pyramid",
    "definition": {
      "meanings": []
    }
  }
}

例句和自定义示例

给已有释义添加例句

curl "$NEATH_API_BASE/words/456/examples" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "meaning_id": "cm_xxx",
    "sentence": "The team built a pyramid.",
    "translation": "团队搭了一个金字塔形。"
  }'

真实响应结构是 { "example": ..., "meaning": ..., "word": ... }。example.id 后续用于删除这条例句。

{
  "example": {
    "id": "ex_xxx",
    "sentence": "The team built a pyramid.",
    "translation": "团队搭了一个金字塔形。",
    "source": "user"
  },
  "meaning": {
    "id": "cm_xxx",
    "examples": []
  },
  "word": {
    "id": 456,
    "word": "pyramid"
  }
}

不指定释义时添加例句

curl "$NEATH_API_BASE/words/456/examples" \
  -H "X-Neath-API-Key: $NEATH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sentence": "A pyramid can be symbolic.",
    "translation": "金字塔也可以具有象征意义。"
  }'

交互逻辑：如果不传 meaning_id，服务端会创建一个新的自定义释义并把例句挂在其下。

删除例句

curl -X DELETE "$NEATH_API_BASE/words/456/examples/ex_xxx" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

真实响应结构：

{
  "deleted": true,
  "example_id": "ex_xxx",
  "word": {
    "id": 456,
    "word": "pyramid"
  }
}

查词

请求

curl "$NEATH_API_BASE/dictionary/lookup?word=example" \
  -H "X-Neath-API-Key: $NEATH_API_KEY"

用途

适合在外部工具里做“先查词，再决定是否加入词书”的流程。

交互逻辑

1. 用户输入或选中文本。
2. 调用查词接口获取释义。
3. 将释义展示给用户确认。
4. 用户确认后，调用添加单词接口写入目标词书。

查到返回 200。暂未就绪或不存在返回 404，响应体仍可能包含可展示的 definition 信息。

如果完全缺少 word 查询参数，FastAPI 会返回 422，响应体是 detail 数组，而不是普通字符串。

错误处理

• 400：请求参数错误，例如名称为空、超出数量限制、不可写系统词书。
• 401：缺少 Key、Key 无效、Key 过期、Key 所属用户不存在。
• 403：Key 缺少所需权限。
• 404：资源不存在，或资源不属于当前用户。
• 409：重复单词，部分场景的 detail 会包含 { "message": "...", "word_id": 123 }。
• 422：FastAPI 请求校验错误，例如缺少必填查询参数 word，响应体是 {"detail":[...]}。
• 429：请求过于频繁。读取 Retry-After 后再重试。

普通业务错误通常是：

{"detail": "Notebook not found"}

校验错误通常是：

{
  "detail": [
    {
      "type": "missing",
      "loc": ["query", "word"],
      "msg": "Field required",
      "input": null
    }
  ]
}

限流错误会返回 429，并包含 Retry-After 响应头。调用方应等待对应秒数后再重试。

同步和审计

• 匿词写操作会同步词灵运行时自定义词书文件 nicicustom<notebook_id>.txt。
• 词灵侧已经学习过的历史卡片不会因 API 删除词条而被直接删除。
• 未学习的过期新卡片会清理，避免继续引入已移除的词。
• 写操作会记录到 neathapikeyauditlogs，包含操作、资源、请求来源和前后快照。