接入方式
向项目管理员申请团队 API Key。密钥与研究工作台账号分开管理；请在每次请求的 Authorization Header 中传入，不要写入 URL、网页代码或公开仓库。
Authorization: Bearer qck_live_<团队密钥>正式环境地址：https://qingci.zhiruitech.com.cn
curl -H "Authorization: Bearer $QINGCI_KNOWLEDGE_API_KEY" \
'https://qingci.zhiruitech.com.cn/api/v1/knowledge/works?q=春&page=1&page_size=20'接口列表
以下路径均使用 GET。详情路径中的 {id} 为正整数编号。
| 资源 | 列表路径 | 详情路径 |
|---|---|---|
| 词作 | /api/v1/knowledge/works | /api/v1/knowledge/works/{id} |
| 历史事件 | /api/v1/knowledge/history/events | /api/v1/knowledge/history/events/{id} |
| 词人生平事件 | /api/v1/knowledge/history/poet-life | /api/v1/knowledge/history/poet-life/{id} |
| 作品史证关联 | /api/v1/knowledge/history/work-links | /api/v1/knowledge/history/work-links/{id} |
参数与返回
所有列表支持 q、page、page_size。q 为字面子串检索，最多 200 字符；页码从 1 开始，默认每页 20 条，最多 100 条。
| 列表 | 额外筛选参数 |
|---|---|
| 词作 | poet 作者、tune_pattern 词牌 |
| 历史事件 | event_type 事件类别、place_name 地点 |
| 词人生平事件 | poet 词人 |
| 作品史证关联 | work_id 作品编号 |
列表响应
{
"items": [...],
"total": 42,
"page": 1,
"page_size": 20
}详情接口直接返回一条 JSON 对象。词作列表包含编号、题名、词牌、时期、正文和作者；详情另含逐句声律。史证包含事件的类别、年代、地点、简介，或作品与事件的关联主张。
V5 声律数据
当前发布范围为冻结 V5 的 700 道公开题和 300 道保密验证题题面涉及的 423 篇词作。调用 GET /api/v1/knowledge/works/{id} 可取得 prosody；其 lines 按句序给出 line_no、text、character_count、ping_count、ze_count。仅有有效字音标注的句子参与统计，标点和空白不计。
{
"prosody": {
"split_after_line": 1,
"lines": [
{"line_no": 1, "text": "示例句。", "character_count": 3, "ping_count": 2, "ze_count": 1}
]
}
}前后段按参与统计的句子顺序，在第 max(1, floor(句数 / 2)) 句之后分段。仄声比例为 ze_count / (ping_count + ze_count) × 100；V5 题面要求保留一位小数。长句阈值为平均句长向上取整。逐句数据可用于复算形式题；接口不提供赛题答案、自动评分或语义结论。
错误处理
| HTTP 状态 | 含义 |
|---|---|
400 | 参数无效或包含未支持的参数 |
401 | 密钥缺失、无效、停用或过期 |
404 | 编号不存在、尚未发布或已撤回 |
405 | 该知识接口不支持写入方法 |
429 | 调用频率超限 |
错误响应为带 error 字段的 JSON。团队密钥默认每分钟 120 次调用，具体额度由管理员创建密钥时设定；遇到 429 请按响应中的 retry_after 秒数重试。
开放范围
仅已审核发布的词作、历史事件、词人生平事件及作品史证关联可被查询；撤回后即不可见。接口不返回内部证据状态、审核过程或审核备注。
独立文献来源、理论主张、研究项目、标注写入、全库导出及智能体对话均不在开放范围内。团队密钥不能调用智能体接口。
若需开通或调整密钥，请联系项目管理员。