方寸 API 文档

格律诗词校验与辅助创作接口。

认证

所有 /api/* 请求需通过 X-API-Key Header 传递 API Key：

X-API-Key: fc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

获取 Key

发送邮件至 guoxue_sjtu@163.com，请包含以下信息：

收件人: guoxue_sjtu@163.com
主　题: 方寸 API Key 申请

您好，

我希望申请方寸 API Key，信息如下：

姓名/团队：
用途说明：
预计调用量：

谢谢！

审核通过后将回复包含 API Key 的邮件。

限流

超限返回 429 Too Many Requests。

错误处理

错误统一返回 JSON：

{ "error": "错误描述" }

参数约束

校验格律

检测诗词的平仄和押韵是否符合规则。这是核心接口。

请求体 (JSON)

请求示例

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

响应示例 — 格律通过

{
  "is_valid": true,
  "closest_rule": {
    "name": "五绝仄起",
    "genre": "Shi",
    "cipai": "Wujue",
    "char_count": 20
  },
  "errors": [],
  "warnings": [],
  "rhyme_name": "十一尤",
  "rhyme_positions": [9, 19],
  "rhyme_chars": ["流", "楼"],
  "rhyme_groups": [
    { "positions": [9, 19], "type": "same" }
  ],
  "rhyme_relations": [],
  "display_segments": [
    {
      "start_index": 0,
      "text_chars": ["白", "日", "依", "山", "尽", "黄", "河", "入", "海", "流"],
      "rule_items": [
        { "tone": "A" }, { "tone": "Z" }, { "tone": "A" },
        { "tone": "P" }, { "tone": "Z" }, { "tone": "P" },
        { "tone": "P" }, { "tone": "A" }, { "tone": "Z" }, { "tone": "P" }
      ]
    }
  ]
}

响应示例 — 有错误

{
  "is_valid": false,
  "closest_rule": {
    "name": "五绝仄起首句入韵",
    "char_count": 20
  },
  "errors": [
    {
      "position": 1,
      "character": "风",
      "error_type": "Tone",
      "message": "应为仄, 实为平"
    },
    {
      "position": 6,
      "character": "雨",
      "error_type": "Tone",
      "message": "应为平, 实为仄"
    }
  ],
  "rhyme_name": "五微",
  "rhyme_chars": ["开", "飞", "归"]
}

响应字段说明

查字

查询单个汉字的声调和所属韵部。支持繁体自动转简体。

示例 — 指定韵书

curl "https://write.sjtuguoxue.space/api/char/lookup?char=花&book=Pingshuiyun" \
  -H "X-API-Key: fc_xxx"

{
  "char": "花",
  "tones": ["平", "上"],
  "rhyme_categories": [
    { "name": "六麻", "tone_type": "P" }
  ]
}

示例 — 不指定韵书（返回所有）

{
  "char": "花",
  "tones": ["平", "上"],
  "rhyme_categories": {
    "Pingshuiyun": ["六麻"],
    "Cilinzhengyun": ["第3部_仄", "第10部_平"]
  }
}

查韵部字表

查看某个韵部包含哪些字。

示例

curl "https://write.sjtuguoxue.space/api/rhyme/lookup?book=Pingshuiyun&category=一东" \
  -H "X-API-Key: fc_xxx"

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

韵部列表

列出韵书中的所有韵部概览。

示例

curl "https://write.sjtuguoxue.space/api/rhyme/list?book=Pingshuiyun&tone=P" \
  -H "X-API-Key: fc_xxx"

{
  "book": "Pingshuiyun",
  "categories": [
    {
      "name": "一东",
      "tone_type": "P",
      "char_count": 392,
      "preview": "中总种同衕东梦红风冲"
    },
    {
      "name": "二冬",
      "tone_type": "P",
      "char_count": 262,
      "preview": "从共重龙供冲封鍾鐘钟"
    }
  ]
}

格律规则列表

列出可用的诗词格律规则或词牌。

示例 — 搜索五绝

curl "https://write.sjtuguoxue.space/api/rules/list?genre=Shi&search=五绝" \
  -H "X-API-Key: fc_xxx"

[
  { "name": "五绝仄起首句入韵", "char_count": 20 },
  { "name": "五绝仄起",         "char_count": 20 },
  { "name": "五绝平起",         "char_count": 20 },
  { "name": "五绝平起首句入韵", "char_count": 20 }
]

词语联想

按首字、尾字查诗词用语，或查对仗字。数据来源于古诗词语料统计。

示例 — 首字联想

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=明&mode=head&length=2" \
  -H "X-API-Key: fc_xxx"

[
  ["明月", 2298],
  ["明朝", 1683],
  ["明日", 1398],
  ["明年", 797],
  ["明时", 296]
]

示例 — 对仗字

curl "https://write.sjtuguoxue.space/api/dictionary/search?term=月&mode=pair" \
  -H "X-API-Key: fc_xxx"

[
  ["风", 4450],
  ["云", 3575],
  ["花", 1386],
  ["山", 1340],
  ["天", 1142]
]

典故检索

检索包含指定字/词的典形词（文学典故），返回释义、典源、同源典形词和古诗例句。数据约 13,000 条。

示例

curl "https://write.sjtuguoxue.space/api/dictionary/allusion?term=月&limit=5" \
  -H "X-API-Key: fc_xxx"

[
  {
    "id": 42,
    "w": "月桂",
    "d": "借指月中桂树，喻科举及第",
    "src": "月中桂",
    "src_text": "《酉阳杂俎》载……",
    "related": [
      { "w": "折桂", "d": "比喻科举登第" },
      { "w": "蟾宫", "d": "借指月宫" }
    ],
    "examples": ["昔年曾向嫦娥妒，今日相逢恐未真"],
    "rc": 5
  }
]

响应字段说明

自由诗韵脚检测

对自由诗（古体诗/新诗/歌词等不限格律的诗体）进行轻量韵脚检测，提取韵脚候选字并按共同韵部前向分组。

示例

curl -X POST https://write.sjtuguoxue.space/api/free_rhyme \
  -H "Content-Type: application/json" \
  -H "X-API-Key: fc_xxx" \
  -d '{"lines": ["春眠不觉晓，", "处处闻啼鸟。", "夜来风雨声，", "花落知多少。"]}'

{
  "candidates": [
    { "line": 0, "pos": 4, "char": "晓", "categories": ["二巧"] },
    { "line": 1, "pos": 4, "char": "鸟", "categories": ["二巧"] },
    { "line": 2, "pos": 4, "char": "声", "categories": ["十一庚"] },
    { "line": 3, "pos": 4, "char": "少", "categories": ["二巧"] }
  ],
  "groups": [
    { "positions": [
      { "line": 0, "pos": 4 },
      { "line": 1, "pos": 4 },
      { "line": 3, "pos": 4 }
    ] }
  ]
}

响应字段说明