PUBLIC API · V1

开放查询接口

无需注册、无需 API Key。所有响应均为 UTF-8 JSON，并返回 Access-Control-Allow-Origin: *，可直接由浏览器或服务端调用。

请求地址

GET https://poetry.fakehistory.top/api/v1/...

公平使用与限流

每个客户端每分钟最多 60 次请求。响应会附带 X-RateLimit-Limit 与 X-RateLimit-Remaining；达到上限时返回 429，并附带 Retry-After。请在客户端缓存结果，避免轮询频率超过实际需要。

端点总览

端点	用途	参数
`GET /api/v1/poems/random`	随机获取一首诗词及作者小传	`dynasty`：`唐` 或 `宋`
`GET /api/v1/poems`	分页检索诗词	`title`、`q`、`author`、`dynasty`、`page`、`per_page`
`GET /api/v1/poems/{id}`	按标识读取完整诗词	路径中的 `id`
`GET /api/v1/authors/{name}`	查询作者资料	可选 `dynasty`；作者名称须 URL 编码

随机获取

curl "https://poetry.fakehistory.top/api/v1/poems/random?dynasty=唐"

{
  "data": {
    "id": "tang-...",
    "title": "帝京篇十首 一",
    "author": "太宗皇帝",
    "dynasty": "唐",
    "form": "诗",
    "paragraphs": ["秦川雄帝宅，函谷壯皇居。"],
    "source": "全唐诗",
    "author_profile": {
      "name": "太宗皇帝",
      "dynasty": "唐",
      "description": "...",
      "short_description": "...",
      "source": "全唐诗"
    }
  }
}

检索与分页

curl "https://poetry.fakehistory.top/api/v1/poems?q=明月&dynasty=宋&page=1&per_page=20"
curl "https://poetry.fakehistory.top/api/v1/poems?author=苏轼"

title 会匹配诗词题目；q 会匹配题目、作者及正文；per_page 默认 20，最大 50；page 从 1 开始。列表响应的 data 是诗词数组，pagination 包含 page、per_page 和 total。

按 ID 与作者查询

curl "https://poetry.fakehistory.top/api/v1/poems/tang-3ad6d468-7ff1-4a7b-8b24-a27d70d00ed4"
curl "https://poetry.fakehistory.top/api/v1/authors/%E8%8B%8F%E8%BD%BC?dynasty=宋"

错误响应

参数不合法时返回 400；资源不存在时返回 404；非 GET 请求返回 405；超过频率限制时返回 429。错误对象包含机器可读的 error 和中文 message 字段。

{
  "error": "rate_limit_exceeded",
  "message": "每位客户端每分钟最多请求 60 次。"
}

数据源为 chinese-poetry。使用者须自行评估资料准确性与下游使用场景，并遵守数据源的 MIT 许可。