单元接口

单元是什么

单元是词库内部的分组，一个词库可以包含多个单元（如「Unit 1 入住办理」「Unit 2 客房服务」），用户通常按单元组织和学习内容。

⚠️ 所有单元操作都必须提供 bookId 参数，用来指定操作哪个词库下的单元。 bookId 通过 词库接口 的 book.list 或 book.create 获取。 缺少 bookId 时接口会返回失败，不要凭空猜测词库 ID。

获取单元列表

POST /ai/invoke
method: unit.list

获取指定词库下的全部单元。

请求体

{
  "method": "unit.list",
  "data": {
    "bookId": "c3d9e4b1a2f3"
  }
}

data 参数：

字段	必填	说明
bookId	是	词库 ID，来自 book.list 或 book.create 的返回结果

请求示例

curl -X POST http://127.0.0.1:27531/ai/invoke \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"method\":\"unit.list\",\"data\":{\"bookId\":\"c3d9e4b1a2f3\"}}"

响应示例

{
  "success": true,
  "data": [
    {
      "unitId": "u1a2b3c4d5e6",
      "unitName": "Unit 1 入住办理"
    },
    {
      "unitId": "u7f8e9d0c1b2",
      "unitName": "Unit 2 客房服务"
    }
  ]
}

响应字段

返回单元数组，每项字段：

字段	说明
unitId	单元 ID，后续操作该单元时使用
unitName	单元名称

备注

• 词库没有任何单元时返回空数组 []。
• 单元按用户看到的顺序返回。

创建单元

POST /ai/invoke
method: unit.create

在指定词库下创建一个新单元，新单元排在已有单元的最后。

请求体

{
  "method": "unit.create",
  "data": {
    "bookId": "c3d9e4b1a2f3",
    "unitName": "Unit 1 入住办理"
  }
}

data 参数：

字段	必填	说明
bookId	是	词库 ID，来自 book.list 或 book.create 的返回结果
unitName	是	单元名称，建议带序号（如「Unit 1 入住办理」），方便用户按顺序学习

请求示例

curl -X POST http://127.0.0.1:27531/ai/invoke \
  -H "Content-Type: application/json; charset=utf-8" \
  -d "{\"method\":\"unit.create\",\"data\":{\"bookId\":\"c3d9e4b1a2f3\",\"unitName\":\"Unit 1 入住办理\"}}"

响应示例

{
  "success": true,
  "data": {
    "unitId": "u5f6e7d8c9b0a",
    "unitName": "Unit 1 入住办理"
  }
}

响应字段

字段	说明
unitId	新单元的 ID，后续往该单元导入内容时使用
unitName	单元名称

备注

• 创建前建议先调用「获取单元列表」确认是否已有合适的单元，避免重复创建。
• 推荐按主题为每批内容新建单元，而不是全部堆在一个单元里，便于用户管理学习进度。