开放接口 API 文档

快速开始

三步完成接入：获取密钥 → 携带请求头 → 解析 data 字段。

1. 获取 API Key

API Key 由本站发放，请邮件至 [email protected] 说明用途与预计调用量。密钥形如 gsc_1f9c…，仅发放时完整显示一次，请保存在服务端配置中，不要写入前端代码或公开仓库。

密钥即身份凭证，请勿分享或转借；额度与有效期以发放时的通知为准。

2. 发起第一个请求

curl "https://www.shicidi.com/api/v1/poems/1" \
  -H "X-API-Key: gsc_你的密钥"

3. 读取数据

响应固定为 { code, message, data, request_id }：code=0 表示成功，业务数据全部在 data 中；分页接口在 data.pagination 返回页码信息。

测试连通性可先调用免鉴权的 GET https://www.shicidi.com/api/v1/ping。

鉴权方式

除 /ping 与 /v1 索引外，所有端点都必须携带 API Key。支持三种传递方式，推荐使用请求头。

方式	写法	建议
请求头（推荐）	`X-API-Key: gsc_xxxxxxxx`	不会被日志记录，兼容性最好
Bearer Token	`Authorization: Bearer gsc_xxxxxxxx`	适合已有 OAuth 风格封装的客户端
查询参数	`?api_key=gsc_xxxxxxxx`	仅用于临时调试，密钥可能留在访问日志中

鉴权失败响应

HTTP/1.1 401 Unauthorized

{
  "code": 1001,
  "message": "缺少 API Key：请在请求头 X-API-Key 中携带密钥",
  "data": null,
  "request_id": "5a1e0c7b9d3f2a84"
}

密钥有效性

密钥可能因安全策略被停用、更换或到期，每次请求都会校验：无效返回 401，停用或过期返回 403。

服务端只保存密钥摘要，无法找回明文；如怀疑密钥泄露，请邮件联系我们更换。

在线调试

输入自己的 API Key，选择端点即可在本页直接发起请求；密钥仅在当前页面使用，不会被保存。

API Key 端点

附加参数（可留空，格式 key=value&key2=value2）

示例：keyword=明月&type=content&per_page=3

响应格式

所有接口返回 UTF-8 编码的 JSON，HTTP 状态码与业务码分离：HTTP 表示请求结果类别，code 表示具体原因。

字段	类型	说明
`code`	int	业务码，0 为成功，其余见「错误码」
`message`	string	结果说明，成功固定为 ok
`data`	object \| array \| null	业务数据，失败时为 null
`request_id`	string	本次请求唯一标识，反馈问题时请提供
`detail`	object	仅部分错误返回，附带提示或示例

分页结构

"pagination": {
  "page": 1,
  "per_page": 20,
  "total": 345614,
  "pages": 17281
}

响应头

响应头	说明
`X-Request-Id`	请求唯一标识，与响应体一致
`X-API-Version`	固定 v1
`X-RateLimit-Limit`	每分钟请求上限
`X-RateLimit-Remaining`	本分钟剩余次数
`X-RateLimit-Reset`	本分钟窗口结束的 Unix 时间戳
`X-Quota-Limit`	每日调用上限
`X-Quota-Remaining`	今日剩余次数
`X-Quota-Reset`	配额重置时间（次日 0 点）的 Unix 时间戳

错误码

code	HTTP	说明
`0`	200	调用成功
`1001`	401	缺少 API Key
`1002`	401	API Key 无效或格式不正确
`1003`	403	API Key 已停用
`1004`	403	API Key 已过期
`1005`	429	超出每分钟请求上限
`1006`	429	当日调用配额已用尽
`2001`	422	参数缺失或不合法（分类、作者不存在等）
`2002`	404	资源或接口不存在
`2003`	405	请求方法不支持（仅 GET）
`5030`	503	开放接口已临时关闭
`5001`	500	服务暂未就绪，请稍后重试
`5000`	500	服务器内部错误

建议客户端对 1005 / 1006 做退避重试，对其余 4xx 直接提示，不要重试。

限流与配额

每分钟限流：按密钥维度统计最近 60 秒的请求数，超出返回 429 / 1005，并带 X-RateLimit-Reset。
每日配额：每个密钥独立计数，每日 0 点重置，超出返回 429 / 1006。
额度以密钥为准：每个密钥独立计费，实时额度见响应头 X-RateLimit-Limit 与 X-Quota-Limit；如需更高额度请邮件联系我们。
不计配额的请求：/ping 与 /v1 索引。
建议：列表接口使用 per_page=100 批量拉取并本地缓存；诗词内容基本不变，适合长期缓存。

接口列表

以下路径均相对于 BASE URL https://www.shicidi.com/api/v1。

GET /categories

分类列表

返回站点全部诗词分类（唐诗、宋词、元曲、诗经等），含分类简介、收录数量与对应页面地址。数据变化不频繁，适合本地缓存。

该端点无需请求参数。

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "唐诗",
        "slug": "tangshi",
        "dynasty": "唐",
        "intro": "唐诗泛指创作于唐代的诗，是中华诗词的高峰……",
        "poem_count": 57590,
        "url": "https://www.example.com/list/tangshi/"
      }
    ],
    "total": 19
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /authors

作者列表

分页获取诗人/作者列表，可按朝代、姓名关键词、存诗数筛选，默认按存诗数量倒序。

请求参数

参数	类型	必填	说明
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100
`dynasty`	string	否	朝代，如唐、宋、先秦
`keyword`	string	否	姓名或拼音模糊匹配，如李白 / libai
`min_poems`	int	否	存诗数量下限，如 100
`sort`	string	否	poems（默认，按存诗数）/ id / name

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "id": 105,
        "name": "李白",
        "pinyin": "li bai",
        "slug": "libai",
        "dynasty": "唐",
        "poem_count": 1015,
        "has_intro": 1,
        "url": "https://www.example.com/shiren/libai.html"
      }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 13651, "pages": 683 }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /authors/{id}

作者详情

按作者 ID、拼音 slug 或姓名获取作者详情，包含完整小传，并附带该作者前 5 首作品，常见场景一次请求即可渲染作者页。

请求参数

参数	类型	必填	说明
`id`	string	是	路径参数：作者 ID、slug 或姓名，如 105 / libai / 李白

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "author": {
      "id": 105,
      "name": "李白",
      "pinyin": "li bai",
      "slug": "libai",
      "dynasty": "唐",
      "poem_count": 1015,
      "has_intro": 1,
      "intro": "李白（701—762），字太白，号青莲居士，唐代浪漫主义诗人……",
      "intro_excerpt": "李白（701—762），字太白，号青莲居士……",
      "url": "https://www.example.com/shiren/libai.html"
    },
    "poems_preview": [
      {
        "id": 1203,
        "title": "静夜思",
        "author": { "id": 105, "name": "李白", "slug": "libai" },
        "dynasty": "唐",
        "category": { "id": 1, "name": "唐诗", "slug": "tangshi" },
        "first_line": "床前明月光",
        "excerpt": "床前明月光，疑是地上霜。",
        "char_count": 20,
        "line_count": 4,
        "is_featured": 1,
        "rhythmic": "",
        "section": "",
        "url": "https://www.example.com/shi/1203.html"
      }
    ],
    "links": {
      "poems": "/api/v1/authors/105/poems",
      "page": "https://www.example.com/shiren/libai.html"
    }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /authors/{id}/poems

作者作品列表

获取某位作者的全部作品，分页返回。参数与「诗词列表」一致（category 等筛选可叠加）。

请求参数

参数	类型	必填	说明
`id`	string	是	路径参数：作者 ID、slug 或姓名
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100
`sort`	string	否	id（默认）/ new / short / long
`with_content`	int	否	传 1 返回正文全文（默认仅摘要）

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "id": 1203,
        "title": "静夜思",
        "author": { "id": 105, "name": "李白", "slug": "libai" },
        "excerpt": "床前明月光，疑是地上霜。",
        "char_count": 20,
        "url": "https://www.example.com/shi/1203.html"
      }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 1015, "pages": 51 },
    "author": { "id": 105, "name": "李白", "slug": "libai", "poem_count": 1015 }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /poems

诗词（文章）列表

核心列表接口。支持按分类、作者、朝代、精选、关键词组合筛选与多种排序，默认返回摘要，传 with_content=1 返回全文。

请求参数

参数	类型	必填	说明
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100
`category`	string	否	分类 slug 或 ID，如 tangshi / 1
`category_id`	int	否	分类 ID（与 category 二选一）
`author_id`	int	否	作者 ID
`author`	string	否	作者 ID / slug / 姓名，如李白
`dynasty`	string	否	朝代，如唐
`featured`	int	否	1 仅精选作品，0 仅非精选
`keyword`	string	否	标题 / 作者 / 正文关键词，最多 30 字
`sort`	string	否	id（默认，按收录顺序）/ new（最新）/ short（短篇优先）/ long（长篇优先）
`with_content`	int	否	传 1 时列表项包含 content 与 lines 全文

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "id": 1203,
        "title": "静夜思",
        "author": { "id": 105, "name": "李白", "slug": "libai" },
        "dynasty": "唐",
        "category": { "id": 1, "name": "唐诗", "slug": "tangshi" },
        "rhythmic": "",
        "section": "",
        "first_line": "床前明月光",
        "excerpt": "床前明月光，疑是地上霜。",
        "char_count": 20,
        "line_count": 4,
        "is_featured": 1,
        "url": "https://www.example.com/shi/1203.html"
      }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 57590, "pages": 2880 }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /poems/{id}

诗词（文章）详情

按 ID 获取单篇作品的完整内容：原文分行、逐行拼音、注释、白话译文、赏析、作者简介、所属分类以及上下篇。

请求参数

参数	类型	必填	说明
`id`	int	是	路径参数：作品 ID，如 1203

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": 1203,
    "title": "静夜思",
    "author": {
      "id": 105,
      "name": "李白",
      "slug": "libai",
      "pinyin": "li bai",
      "dynasty": "唐",
      "poem_count": 1015,
      "has_intro": 1,
      "intro": "李白（701—762），字太白，号青莲居士……",
      "url": "https://www.example.com/shiren/libai.html"
    },
    "dynasty": "唐",
    "category": { "id": 1, "name": "唐诗", "slug": "tangshi", "dynasty": "唐", "url": "https://www.example.com/list/tangshi/" },
    "content": "床前明月光\n疑是地上霜\n举头望明月\n低头思故乡",
    "lines": ["床前明月光", "疑是地上霜", "举头望明月", "低头思故乡"],
    "pinyin": "chuang qian ming yue guang|yi shi di shang shuang|ju tou wang ming yue|di tou si gu xiang",
    "pinyin_lines": ["chuang qian ming yue guang", "yi shi di shang shuang", "ju tou wang ming yue", "di tou si gu xiang"],
    "notes": "① 静夜思：安静的夜晚产生的思绪。",
    "notes_lines": ["① 静夜思：安静的夜晚产生的思绪。"],
    "translation": "明亮的月光洒在床前，好像地上泛起了一层白霜……",
    "translation_lines": ["明亮的月光洒在床前，好像地上泛起了一层白霜……"],
    "appreciation": "这首诗写的是在寂静的月夜思念家乡的感受……",
    "appreciation_lines": ["这首诗写的是在寂静的月夜思念家乡的感受……"],
    "first_line": "床前明月光",
    "excerpt": "床前明月光，疑是地上霜。",
    "char_count": 20,
    "line_count": 4,
    "is_featured": 1,
    "rhythmic": "",
    "section": "",
    "url": "https://www.example.com/shi/1203.html",
    "prev": { "id": 1202, "title": "…", "url": "https://www.example.com/shi/1202.html" },
    "next": { "id": 1204, "title": "…", "url": "https://www.example.com/shi/1204.html" }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /search

全文检索

按标题、作者或诗句全文检索作品。有 ngram 全文索引时走索引，否则自动退化为 LIKE，结果均为分页。

请求参数

参数	类型	必填	说明
`keyword`	string	是	检索关键词，最多 30 字
`type`	string	否	all（默认）/ title / author / content
`category`	string	否	限定分类 slug 或 ID
`page`	int	否	页码，默认 1
`per_page`	int	否	每页条数，默认 20，最大 100
`with_content`	int	否	传 1 返回正文全文

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "keyword": "静夜思",
    "type": "all",
    "list": [
      {
        "id": 1203,
        "title": "静夜思",
        "author": { "id": 105, "name": "李白", "slug": "libai" },
        "excerpt": "床前明月光，疑是地上霜。",
        "url": "https://www.example.com/shi/1203.html"
      }
    ],
    "pagination": { "page": 1, "per_page": 20, "total": 37, "pages": 2 }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /stats

站点统计

返回站点收录总量、分类分布与更新时间，适合做首页数据面板或健康监控。

该端点无需请求参数。

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "totals": { "poems": 345614, "authors": 13651, "categories": 19, "featured": 1200 },
    "categories": [
      { "id": 1, "name": "唐诗", "slug": "tangshi", "dynasty": "唐", "poem_count": 57590 }
    ],
    "imported_at": "2026-10-30 12:21:09",
    "site": {
      "name": "中国古诗网",
      "slogan": "诗者，志之所之也",
      "url": "https://www.example.com"
    }
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

GET /ping

健康检查

免鉴权端点，用于连通性测试与监控探活，不消耗调用配额。

该端点无需请求参数。

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "ok",
    "time": "2026-11-03T14:20:31+08:00",
    "api": "v1",
    "site": "中国古诗网"
  },
  "request_id": "9c3f1b7d2a4e5f60"
}

字段说明

poem（作品 / 文章）

字段	类型	说明
`id`	int	作品 ID，可用于详情页与详情接口
`title`	string	标题
`author`	object	{ id, name, slug }
`dynasty`	string	朝代
`category`	object	{ id, name, slug }
`rhythmic`	string	词牌 / 曲牌，无则为空串
`section`	string	所属篇章 / 卷次
`content`	string	原文，段落以 \n 分隔（仅详情或 with_content=1）
`lines`	string[]	原文按行拆分（仅详情或 with_content=1）
`pinyin`	string	拼音原文，行内空格分隔、行间以竖线分隔（仅详情）
`pinyin_lines`	string[]	与 lines 一一对齐的逐行拼音（仅详情）
`notes` / `notes_lines`	string / string[]	注释（仅详情）
`translation` / `translation_lines`	string / string[]	白话译文（仅详情）
`appreciation` / `appreciation_lines`	string / string[]	赏析（仅详情）
`first_line`	string	首句
`excerpt`	string	前两句摘要
`char_count` / `line_count`	int	字数 / 句数
`is_featured`	int	1 为精选
`prev` / `next`	object \| null	同分类上下篇 { id, title, url }（仅详情）
`url`	string	对应的网页地址

author（作者）

字段	类型	说明
`id`	int	作者 ID
`name`	string	姓名
`pinyin`	string	姓名拼音
`slug`	string	拼音标识，可用于按 slug 查询
`dynasty`	string	朝代
`poem_count`	int	收录作品数
`has_intro`	int	是否有小传
`intro` / `intro_excerpt`	string	完整小传 / 摘要（详情接口）
`url`	string	诗人页面地址

category（分类）

字段	类型	说明
`id`	int	分类 ID
`name`	string	分类名称
`slug`	string	分类标识，如 tangshi
`dynasty`	string	主要朝代
`intro`	string	分类简介
`poem_count`	int	收录数量

调用示例

curl

curl "https://www.shicidi.com/api/v1/poems?category=tangshi&per_page=5" \
  -H "X-API-Key: gsc_你的密钥"

JavaScript（浏览器 / Node 18+）

const res = await fetch("https://www.shicidi.com/api/v1/authors?keyword=李白", {
  headers: { "X-API-Key": "gsc_你的密钥" }
});
const json = await res.json();
if (json.code !== 0) throw new Error(json.message);
console.log(json.data.list, json.data.pagination);

PHP

$ch = curl_init("https://www.shicidi.com/api/v1/poems/1203");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: gsc_你的密钥"],
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($json['code'] ?? -1) === 0) {
    echo $json['data']['title'];      // 静夜思
    echo $json['data']['translation'];
}

Python

import requests

r = requests.get("https://www.shicidi.com/api/v1/search",
                 params={"keyword": "静夜思", "per_page": 3},
                 headers={"X-API-Key": "gsc_你的密钥"},
                 timeout=10)
data = r.json()
for item in data["data"]["list"]:
    print(item["id"], item["title"], item["author"]["name"])

常见问题

返回 401 / 1002「API Key 无效」

确认密钥完整复制（以 gsc_ 开头，共 44 个字符），且请求头名称为 X-API-Key；若改用 Authorization，请确认中间代理没有丢弃该请求头。

返回 429

先看响应头 X-RateLimit-Reset / X-Quota-Reset 决定退避时长；列表请求建议合并为更少的批量请求（per_page=100）并本地缓存，详情与分类数据可缓存数天。

拼音如何与正文对齐

详情接口的 lines[n] 与 pinyin_lines[n] 一一对应；每行拼音内以空格分隔，按汉字顺序对应，标点不占位，缺字位置为 - 或空串。

数据可以商用吗

如何反馈问题

请附上响应中的 request_id 与请求地址、时间，便于我们定位问题。联系方式见关于页。