方寸格律检测 API

中国古典诗词格律校验、音韵查询、韵脚分析。所有音韵数据的唯一事实来源。

简介

本服务提供 9 个 API 端点，支持：

能力	端点
格律检测（单首，完整响应）	`POST /api/validate_meter`
格律检测（批量，compact 响应）	`POST /api/validate_batch`
自由诗韵脚分析	`POST /api/free_rhyme`
单字音韵查询	`GET /api/char/lookup`
批量字音查询	`POST /api/char/batch`
韵部同韵字查询	`GET /api/rhyme/lookup`
韵部列表	`GET /api/rhyme/list`
格律规则列表	`GET /api/rules/list`
示例作品	`GET /api/examples`

无需认证，公开访问。返回 JSON。

Base URL

https://checker.sjtuguoxue.space

限流

按 IP 限流。大部分端点 600 次/分钟，validate_batch 为 30 次/分钟（每批最多 100 首）。超限返回 429。

参数约束

参数	可选值
genre	`Shi`（诗）、`Ci`（词）
book / rhyme_book_name	`Pingshuiyun`（平水韵）、`Cilinzhengyun`（词林正韵）、`Zhonghua_Tongyun`（中华通韵）

校验格律

核心接口。检测诗词的平仄和押韵是否符合格律规则。返回逐字谱面、结构化错误（含 expected/actual）、韵部信息。

POST /api/validate_meter

请求体 (JSON)

字段	类型		说明
poem_text	string	必填	诗词文本（标点自动忽略，只提取汉字）
genre	string	可选	`Shi`（诗）或 `Ci`（词），默认 `Shi`
rhyme_book_name	string	可选	韵书名，默认 `Pingshuiyun`。可选：`Pingshuiyun`（平水韵）、`Cilinzhengyun`（词林正韵，词用旧韵时务必选此项）、`Zhonghua_Tongyun`（中华通韵）
rule_name	string	可选	指定规则名（如 `沁园春_龙谱_格一`），不传则自动匹配
ensure_longpu	bool	可选	仅匹配龙谱规则，默认 `false`
warnings	string \| string[]	可选	重字检测模式，默认 `default`。可选值见下方
include_punctuation	bool	可选	是否检测句读标点，默认 `false`。为 `true` 时，`poem_text` 应带标点，检测器将校验韵(。)、句(，)、读(、)标点是否正确

warnings 可选值

值	说明
`default`	标准重字检测（叠词豁免），不传时默认
`2gram`	连续两字组合（2-gram）重复检测
`rhyme_duplicate`	仅检测韵脚位置之间的重字
`none`	不检测重字，不可与其他值组合

支持数组组合，如 ["default", "rhyme_duplicate"]（两种检测结果拼接返回）。

请求示例

curl -X POST https://checker.sjtuguoxue.space/api/validate_meter \
  -H "Content-Type: application/json" \
  -d '{
    "poem_text": "白日依山尽，黄河入海流。欲穷千里目，更上一层楼。",
    "genre": "Shi",
    "rhyme_book_name": "Pingshuiyun"
  }'

响应字段

字段	类型	说明
is_valid	bool	格律是否通过
closest_rule	object	匹配的规则（name, genre, cipai, char_count）
chars	string[]	清洗后的汉字数组
tone_pattern	string[]	逐字期望声调：`P`(平) / `Z`(仄) / `A`(中，不限)
errors	array	错误列表（见下方）
warnings	array	警告列表（如重字提示）
rhyme_name	string?	检测到的韵部名（如 `十一尤`），换韵时为 `(换韵)`
rhyme_positions	int[]	韵脚所在位置（0-based）
rhyme_chars	string[]	韵脚字

error 对象

字段	类型	说明
position	int	出错位置（0-based）
character	string	出错的字
error_type	string	`Tone`（平仄）或 `Rhyme`（押韵）
expected	string	期望值（Tone: `P`/`Z`；Rhyme: 目标韵部名）
actual	string	实际值（Tone: `P`/`Z`；Rhyme: 实际韵部名）
message	string	人类可读描述

warning 对象

字段	类型	说明
positions	int[]	出现位置（0-based）
character	string	重复的字（2gram 模式为两字组合）
warning_type	string	`Duplicate`（标准重字）、`Duplicate_2gram`（2-gram）、`Rhyme_Duplicate`（韵脚重字）
message	string	人类可读描述

AI Agent 提示：用 tone_pattern 了解全局谱面要求，用 error 的 expected/actual 定位需替换的字及目标声调。修字后重新调用 validate 验证。

LLM / Agent 填词建议：填词时强烈建议开启 "include_punctuation": true。词牌句读结构复杂（韵、句、读交替），标点检测会返回每个位置应使用的标点类型（韵→句号、句→逗号、读→顿号），帮助模型准确断句，避免句读错位。

批量校验格律

一次请求检测多首诗词。返回精简的 compact 结果（不含 display_segments、tone_pattern 等渲染数据），体积约为完整响应的 10%。需要完整数据时对单首调用 validate_meter。

POST /api/validate_batch

请求体 (JSON)

字段	类型		说明
items	array	必填	每个元素与 `validate_meter` 请求体一致（含 `warnings` 参数），最多 100 首

请求示例

curl -X POST https://checker.sjtuguoxue.space/api/validate_batch \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"poem_text": "白日依山尽，黄河入海流。欲穷千里目，更上一层楼。", "genre": "Shi"},
      {"poem_text": "床前明月光，疑是地上霜。举头望明月，低头思故乡。", "genre": "Shi"}
    ]
  }'

响应字段（compact，每首）

字段	类型	说明
is_valid	bool	格律是否通过
closest_rule	object	匹配的规则
errors	array	错误列表
warnings	array	警告列表
rhyme_name	string?	检测到的韵部名

限流：30 次/分钟，每批最多 100 首。用于批量审查场景。

自由韵脚检测

分析自由诗/古体诗的韵脚规律。自动识别句末韵脚字并按韵部分组。

POST /api/free_rhyme

请求体 (JSON)

字段	类型		说明
lines	string[]	必填	诗句数组（每行一个字符串，最多 100 行）
rhyme_book_name	string	可选	韵书名，默认 `Zhonghua_Tongyun`
merge_tones	bool	可选	是否合并平仄声韵（新诗/歌词建议 `true`），默认 `false`

请求示例

curl -X POST https://checker.sjtuguoxue.space/api/free_rhyme \
  -H "Content-Type: application/json" \
  -d '{
    "lines": ["卖炭翁，伐薪烧炭南山中", "满面尘灰烟火色，两鬓苍苍十指黑"],
    "rhyme_book_name": "Pingshuiyun"
  }'

响应字段

字段	类型	说明
candidates	array	所有韵脚候选字（line, pos, char, categories）
groups	array	按韵部分组的押韵组（每组含 positions 数组）

查字音韵

查询单个汉字的声调和韵部归属。

GET /api/char/lookup

查询参数

参数		说明
char	必填	要查询的汉字
book	可选	韵书名，传入后返回该韵书下的韵部（含声调类型排序）

请求示例

curl "https://checker.sjtuguoxue.space/api/char/lookup?char=东&book=Pingshuiyun"

响应示例

{
  "char": "东",
  "tones": ["平"],
  "rhyme_categories": [
    { "name": "一东", "tone_type": "P" }
  ]
}

不传 book 时，rhyme_categories 返回所有韵书的韵部归属（dict 格式）。

批量查字音韵

一次请求查询多个汉字的声调和韵部。每个元素的结构与 char/lookup 响应一致。

POST /api/char/batch

请求体 (JSON)

字段	类型		说明
chars	string[]	必填	汉字数组，最多 200 个
book	string	可选	韵书名，行为与 `char/lookup?book=` 一致

请求示例

curl -X POST https://checker.sjtuguoxue.space/api/char/batch \
  -H "Content-Type: application/json" \
  -d '{"chars": ["大","江","东","去"], "book": "Pingshuiyun"}'

响应示例

[
  { "char": "大", "tones": ["去"], "rhyme_categories": [{ "name": "九泰", "tone_type": "Z" }, ...] },
  { "char": "江", "tones": ["平"], "rhyme_categories": [{ "name": "三江", "tone_type": "P" }] },
  ...
]

查韵部字表

查询指定韵部的所有同韵字（按词频排序）。

GET /api/rhyme/lookup

查询参数

参数		说明
book	可选	韵书名，默认 `Pingshuiyun`
category	必填	韵部名（如 `一东`）
include	可选	包含关联韵部，逗号分隔（如 `neighbor,ye_ping`）

请求示例

curl "https://checker.sjtuguoxue.space/api/rhyme/lookup?book=Pingshuiyun&category=一东"

响应示例

{
  "category_name": "一东",
  "tone_type": "P",
  "total": 45,
  "characters": ["东", "同", "中", "风", ...],
  "relations": { "neighbor": ["二冬"] }
}

韵部列表

列出指定韵书的所有韵部概览。

GET /api/rhyme/list

查询参数

参数		说明
book	可选	韵书名，默认 `Pingshuiyun`
tone	可选	按声调过滤：`P`(上平/下平)、`Z`(上/去)、`R`(入)

请求示例

curl "https://checker.sjtuguoxue.space/api/rhyme/list?book=Pingshuiyun"

响应示例

{
  "book": "Pingshuiyun",
  "categories": [
    { "name": "一东", "tone_type": "P", "char_count": 45, "preview": "东同中风空" },
    { "name": "二冬", "tone_type": "P", "char_count": 29, "preview": "冬农宗钟龙" },
    ...
  ]
}

格律规则列表

列出所有可用的格律规则（诗 16 条，词 2500+ 条）。

GET /api/rules/list

查询参数

参数		说明
genre	可选	`Shi` 或 `Ci`，默认 `Ci`
search	可选	按名称或词牌搜索

请求示例

curl "https://checker.sjtuguoxue.space/api/rules/list?genre=Shi"

响应示例

[
  {
    "name": "七律平起首句入韵",
    "char_count": 56,
    "cipai": "Qilyu",
    "sentence_length": 7,
    "sentence_count": 8,
    "start_tone": "A",
    "first_line_rhyme": true,
    "tone_pattern": ["A", "P", "A", "Z", ...]
  },
  ...
]

词牌搜索：?genre=Ci&search=沁园春 返回所有沁园春变体。

示例作品

按格律规则名称检索历史范作，支持分页。

GET /api/examples

查询参数

参数		说明
rule_name	必填	格律规则名称，如 `水调歌头_龙谱_格一`
limit	可选	返回条数，1-50，默认 `5`
offset	可选	跳过前 N 条，默认 `0`

请求示例

curl "https://checker.sjtuguoxue.space/api/examples?rule_name=水调歌头_龙谱_格一&limit=2"

响应示例

{
  "rule": "水调歌头_龙谱_格一",
  "total": 458,
  "limit": 2,
  "offset": 0,
  "results": [
    {
      "id": 648,
      "title": "水调歌头·戏为人题醉钟馗",
      "author": "夏孙桐",
      "dynasty": "清末民国初",
      "type": "词",
      "content": "天醉久难醒，得酒即为仙。……"
    },
    ...
  ]
}

不清楚规则名称？先调用 GET /api/rules/list?genre={genre}&search={q} 查询可用规则。

方寸格律检测 · 独立基础设施服务
源码：github.com/lyy0323/check_rhyme · 主项目：github.com/lyy0323/fangcun