寻诗 API 文档

744,571 首古诗词的检索与取数接口：繁简双列（content / content_tr）与逐字平仄（strains）为本库独有字段。

快速开始

所有接口以 https://xunshi.oldmen.cn 为基址，请求带 X-API-Key 头。以下示例可直接复制运行。

bash · curl
curl -s "https://xunshi.oldmen.cn/api/v1/search?q=明月几时有" \
  -H "X-API-Key: $XUNSHI_KEY"
json · 200 响应（截断）
{
  "code": 0,
  "message": "ok",
  "data": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "hasMore": false,
    "items": [
      { "id": 56, "title": "水调歌头", "title_tr": "水調歌頭",
        "author": "苏轼", "dynasty": "宋", "kind_cn": "词",
        "content": "明月几时有？把酒问青天。…",
        "content_tr": "明月幾時有？把酒問青天。…",
        "is_bibei": true, "has_strain": true, "has_annotation": true }
    ]
  }
}

认证

免费档需注册换取 API Key。明文 Key 仅在注册响应中返回一次，请立即保存；服务端仅存哈希。

  1. 1提交注册POST /api/v1/auth/register，返回一次性明文 Key。
  2. 2保存 Key加入请求头 X-API-Key；Key 以 •••• 遮蔽展示。
  3. 3发起首个请求调用 GET /api/v1/healthz 验证连通。
用于在配额页标识用途，可留空。
仅在配额调整时联系，不做营销。

注册接口自身限流 3 次/小时/IP。

端点（12 个）

方法路径说明
POST /api/v1/auth/register 注册换取 API Key（免审核；明文 Key 仅返回一次）
GET /api/v1/auth/me 查询当前 Key 的状态与配额用量
GET /api/v1/poems 分页列出作品（支持朝代 / 体裁筛选）
GET /api/v1/poems/random 随机取一首（可选范围参数）
GET /api/v1/poems/{id} 按 id 取作品全字段（含 content / content_tr 双列）
GET /api/v1/search 全文检索（≥3 字走 FTS5，1–2 字走 LIKE）
GET /api/v1/authors 分页列出作者
GET /api/v1/authors/{id} 按 id 取作者与小传
GET /api/v1/strains/{id} 逐字平仄串（含 strain_aligned 对齐标记） 本库独有
GET /api/v1/anthologies 列出全部选本及其作品数
GET /api/v1/anthology/{book} 按选本取篇目
GET /api/v1/healthz 服务健康检查

示例：GET /api/v1/search —— 返回字段 content / content_tr（繁简双列）与 strains（逐字平仄）为本库独有，务必对照下方参数表与响应示例。

bash
curl -s "https://xunshi.oldmen.cn/api/v1/search?q=明月%20几时有&dynasty=宋" \
  -H "X-API-Key: $XUNSHI_KEY"
参数必填说明
q是检索词；≥3 字走 FTS5，1–2 字走 LIKE 降级
dynasty否朝代过滤，如 宋
kind否体裁过滤，如 词
page否页码，默认 1；每页 20 条

数据模型

字段类型说明
id / title / title_trnumber / string作品 id 与简繁标题
content / content_trstring本库独有：繁体为库内原生列直出，非运行时转换
strainsstring | null本库独有：逐字平仄串，字符集 平/仄/○/？
strain_alignedboolean平仄串与正文是否逐字对齐；false 时请按原串展示
is_bibei / has_strain / has_annotationboolean精选与数据可用性标识

错误码

HTTPcode场景message
4001001参数错误invalid parameter: q is required
4011005无 Key / 无效 Key / Key 已停用（未超防刷档）missing or invalid api key
4041002资源不存在poem not found
4291003已注册 Key 超分钟限额（scope=key）rate limit exceeded, retry in 42s
4291003未注册 / 无效 Key 超 IP 防刷档（scope=ip）rate limit exceeded without a valid key; register at /api to get a key
4291004超日配额（10,000 次/天/key）daily quota exceeded (10000/day); resets at 00:00 UTC+8

401 / 429 归类规则：同一调用方无 Key 时先收 401（尚未超防刷档）；持续超限后转 429（scope=ip）。两类响应由「是否超限」决定，状态码与文案均不同，属预期行为，不得混用。

429 响应体 data 载荷（RateLimitedData，6 个必填字段）：

json · 429
{
  "code": 1003,
  "message": "rate limit exceeded, retry in 42s",
  "data": {
    "limit": 60,
    "window": "minute",
    "scope": "key",
    "retry_after": 42,
    "reset_at": "2026-10-12T12:34:00+08:00",
    "upgrade_hint": "免费档限额说明与申请提额方式见 /api 页服务条款"
  }
}

速率限制

已注册 Key 档60 次 / 分钟 · 10,000 次 / 天

其中 1–2 字 LIKE 降级查询限 10 次/分钟/key；降级路径 P95 约 0.3–0.9 秒，返回计数为近似值。

未注册 IP 防刷档20 次 / 分钟 · 1,000 次 / 天

判定先于鉴权：无 Key / 无效 Key 的调用先过防刷档；超限转 429 scope=ip。

注册接口3 次 / 小时 / IP

申请提额与完整契约见 健康检查 与 OpenAPI 规范 /openapi.yaml（v1.3.0）。