API 参考文档

Poetry Gateway · 统一响应格式 · RESTful API

快速导航

聚合接口诗词接口作者接口搜索接口海报接口 AI 接口 🔒用户接口收藏接口 🔒阅读历史接口 🔒阅读统计接口

统一响应格式

成功 200

{
  "success": true,
  "data": { ... }
}

失败

{
  "success": false,
  "code": "NOT_FOUND",
  "message": "资源不存在"
}

错误码：VALIDATION_ERROR (400) · UNAUTHORIZED (401) · NOT_FOUND (404) · RATE_LIMITED (429) · INTERNAL_ERROR (500) · UPSTREAM_ERROR (502)

聚合接口

GET/api/v1/home首页聚合数据：推荐诗词 + 推荐作者 + 统计数据

请求示例

curl /api/v1/home

响应示例

{
  "success": true,
  "data": {
    "featuredPoem": { "id": 1, "title": "静夜思", "content": "床前明月光...", "author": "李白", "dynasty": "唐", "type": "五言绝句" },
    "featuredAuthor": { "id": 1, "name": "李白", "dynasty": "唐", "poemCount": 896 },
    "totalPoems": 385000,
    "totalAuthors": 14000
  }
}

GET/api/v1/discover发现页：近期诗词 + 朝代列表 + 体裁列表

请求示例

curl /api/v1/discover

响应示例

{
  "success": true,
  "data": {
    "recentPoems": [ ... ],
    "dynasties": [ { "id": 1, "name": "唐" }, ... ],
    "types": [ { "id": 1, "name": "五言绝句" }, ... ]
  }
}

GET/api/v1/categories分类聚合：所有朝代 + 所有体裁

请求示例

curl /api/v1/categories

响应示例

{
  "success": true,
  "data": {
    "dynasties": [ { "id": 1, "name": "唐" }, ... ],
    "types": [ { "id": 10, "name": "五言绝句" }, ... ]
  }
}

GET/api/v1/recommend为你推荐 — 随机翻页 + 多样化推荐理由

请求示例

curl /api/v1/recommend

响应示例

{
  "success": true,
  "data": {
    "poems": [ ... ],
    "reason": "经典永流传"
  }
}

GET/api/v1/quote每日一句 — 同一天返回相同诗句，带日期字段，适合 App 开屏

请求示例

curl /api/v1/quote

响应示例

{
  "success": true,
  "data": {
    "content": "床前明月光，疑是地上霜",
    "author": "李白",
    "source": "静夜思",
    "date": "2026-07-23"
  }
}

GET/api/v1/solar-term节气推荐 — 根据当前24节气推荐应景诗词，缓存6小时

请求示例

curl /api/v1/solar-term

响应示例

{
  "success": true,
  "data": {
    "termName": "大暑",
    "termDescription": "炎热至极，一年中最热时期，荷花盛开",
    "poem": { "id": 42, "title": "...", "content": "...", "author": "...", "dynasty": "...", "type": "..." },
    "reason": "今日大暑，为你精选一首夏季诗词"
  }
}

GET/api/v1/config客户端配置：版本号、功能开关、Banner 列表（含图片/标题/跳转链接）

请求示例

curl /api/v1/config

响应示例

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "banners": [
      { "id": "spring", "imageUrl": "https://...", "title": "春日诗词鉴赏", "link": "/browse?dynasty=唐", "sort": 1 }
    ],
    "features": { "aiAnalysis": true, "aiAsk": true, "solarTerm": true, "dailyQuote": true, ... }
  }
}

诗词接口

GET/api/v1/poems诗词列表，支持分页和筛选

参数

名称	类型	说明
page	`number`	页码，默认 1
pageSize	`number`	每页数量，默认 20，最大 100
dynasty	`string`	按朝代筛选
type	`string`	按体裁筛选
author	`string`	按作者筛选

请求示例

curl "/api/v1/poems?page=1&pageSize=10&dynasty=唐&type=五言绝句"

响应示例

{
  "success": true,
  "data": {
    "poems": [ { "id": 1, "title": "...", "content": "...", "author": "...", "dynasty": "...", "type": "..." } ],
    "total": 18895,
    "page": 1,
    "pageSize": 10
  }
}

GET/api/v1/poems/:id诗词详情

请求示例

curl /api/v1/poems/1

响应示例

{
  "success": true,
  "data": {
    "id": 1, "title": "静夜思", "content": "床前明月光，疑是地上霜。举头望明月，低头思故乡。",
    "author": "李白", "dynasty": "唐", "type": "五言绝句"
  }
}

GET/api/v1/poems/random随机获取一首诗词

参数

名称	类型	说明
author	`string`	按作者筛选
type	`string`	按体裁筛选
dynasty	`string`	按朝代筛选
char	`string`	包含指定字（飞花令场景）

请求示例

curl "/api/v1/poems/random?author=李白&type=五言绝句"

响应示例

{ "success": true, "data": { "id": 42, "title": "...", "content": "...", "author": "李白", ... } }

作者接口

GET/api/v1/authors作者列表

参数

名称	类型	说明
page	`number`	页码，默认 1
pageSize	`number`	每页数量，默认 20

请求示例

curl "/api/v1/authors?page=1&pageSize=20"

响应示例

{
  "success": true,
  "data": {
    "authors": [ { "id": 1, "name": "李白", "dynasty": "唐", "description": "...", "poemCount": 896 } ],
    "total": 14000, "page": 1, "pageSize": 20
  }
}

GET/api/v1/authors/:id作者详情

请求示例

curl /api/v1/authors/1

响应示例

{ "success": true, "data": { "id": 1, "name": "李白", "dynasty": "唐", "description": "字太白...", "poemCount": 896 } }

搜索接口

GET/api/v1/search全文搜索诗词

参数

名称	类型	说明
q	`string`	搜索关键词（必填）
type	`enum`	搜索类型：all / title / content / author，默认 all
page	`number`	页码，默认 1
pageSize	`number`	每页数量，默认 20

请求示例

curl "/api/v1/search?q=静夜思&type=title"

响应示例

{
  "success": true,
  "data": {
    "poems": [ ... ],
    "total": 1, "page": 1, "pageSize": 20,
    "query": "静夜思"
  }
}

海报接口

POST/api/v1/poster生成诗词海报 — 服务端渲染 1080×1440 竖版海报，返回 SVG 与 PNG（10 次/分钟限流）

参数

名称	类型	说明
poemId	`number`	诗词 ID（正整数，与 title+content 二选一，提供时优先并按库中内容生成）
title	`string`	标题 1-64 字（自定内容时与 content 同时必填）
content	`string`	正文 1-5000 字（自定内容时必填）
author	`string`	作者，≤32 字（可空）
dynasty	`string`	朝代，≤16 字（可空）
theme	`enum`	主题：ink 水墨 / sunset 落日 / night 夜月，默认 ink
filter	`enum`	滤镜：none 原片 / sepia 复古 / warm 暖阳 / cool 清冷 / gray 黑白 / vivid 明艳，默认 none
format	`enum`	返回格式：svg / png / both，默认 both

请求示例

curl -X POST /api/v1/poster \
  -H "Content-Type: application/json" \
  -d '{"poemId":1,"theme":"night","filter":"warm","format":"both"}'

响应示例

{
  "success": true,
  "data": {
    "svg": "<svg width="1080" height="1440" ...>...</svg>",
    "pngBase64": "iVBORw0KGgo...（纯 base64 字符串；format 为 png/both 且服务端存在中文字体时返回）",
    "width": 1080,
    "height": 1440,
    "theme": "night",
    "filter": "warm",
    "filename": "静夜思_night_warm.png",
    "title": "静夜思",
    "author": "李白",
    "dynasty": "唐"
  }
}

AI 接口 🔒

POST/api/v1/ai/analyse🔒 需认证AI 诗词赏析 — 返回创作背景、赏析、关键词、情感分析

参数

名称	类型	说明
title	`string`	诗词标题（必填）
content	`string`	诗词正文（必填）
author	`string`	作者
dynasty	`string`	朝代

请求示例

curl -X POST /api/v1/ai/analyse \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"静夜思","content":"床前明月光...","author":"李白","dynasty":"唐"}'

响应示例

{
  "success": true,
  "data": {
    "background": "李白在扬州旅舍所作...",
    "appreciation": "此诗以明白如话的语言...",
    "keywords": ["思乡", "明月", "孤独"],
    "emotions": ["思乡之情", "孤寂之感"]
  }
}

POST/api/v1/ai/ask🔒 需认证AI 诗词问答 — 自由提问古诗词相关问题

参数

名称	类型	说明
question	`string`	问题（必填）
context	`string`	参考诗词内容（可选）

请求示例

curl -X POST /api/v1/ai/ask \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"question":"李白和杜甫的风格有什么不同？"}'

响应示例

{ "success": true, "data": { "answer": "李白与杜甫是唐代诗坛的双子星座..." } }

POST/api/v1/ai/translate🔒 需认证AI 诗词翻译 — 支持英/日/韩三种语言

参数

名称	类型	说明
content	`string`	诗词内容（必填）
targetLang	`enum`	目标语言：en / ja / ko，默认 en

请求示例

curl -X POST /api/v1/ai/translate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content":"床前明月光","targetLang":"en"}'

响应示例

{
  "success": true,
  "data": {
    "translation": "Moonlight before my bed...",
    "notes": ["床：指井栏或坐具，非现代意义的床"]
  }
}

用户接口

POST/api/v1/user/register用户注册

参数

名称	类型	说明
email	`string`	邮箱（必填）
password	`string`	密码，最少 6 位（必填）
name	`string`	昵称（可选）

请求示例

curl -X POST /api/v1/user/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"123456","name":"诗词爱好者"}'

响应示例

{ "success": true, "data": { "token": "eyJ...", "user": { "id": "...", "email": "user@example.com", "name": "诗词爱好者" } } }

POST/api/v1/user/login用户登录，返回 JWT Token

参数

名称	类型	说明
email	`string`	邮箱（必填）
password	`string`	密码（必填）

请求示例

curl -X POST /api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"123456"}'

响应示例

{ "success": true, "data": { "token": "eyJhbGciOiJIUzI1NiIs...", "user": { "id": "...", "email": "user@example.com", "name": "诗词爱好者", "avatar": null, "createdAt": "2026-07-22T..." } } }

GET/api/v1/user/profile🔒 需认证获取当前用户信息

请求示例

curl /api/v1/user/profile \
  -H "Authorization: Bearer <token>"

响应示例

{ "success": true, "data": { "id": "...", "email": "user@example.com", "name": "诗词爱好者", "avatar": null, "createdAt": "..." } }

PUT/api/v1/user/profile🔒 需认证更新用户信息

参数

名称	类型	说明
name	`string`	新昵称
avatar	`string`	头像 URL

请求示例

curl -X PUT /api/v1/user/profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"新昵称"}'

响应示例

{ "success": true, "data": { "id": "...", "email": "user@example.com", "name": "新昵称", ... } }

收藏接口 🔒

GET/api/v1/favorites🔒 需认证获取收藏列表

请求示例

curl /api/v1/favorites -H "Authorization: Bearer <token>"

响应示例

{ "success": true, "data": { "favorites": [ { "id": "...", "poemId": "1", "poemTitle": "静夜思", "poemAuthor": "李白", "poemDynasty": "唐", "createdAt": "..." } ], "total": 1 } }

POST/api/v1/favorites🔒 需认证添加收藏

参数

名称	类型	说明
poemId	`string`	诗词 ID（必填）
poemTitle	`string`	诗词标题（必填）
poemAuthor	`string`	作者
poemDynasty	`string`	朝代

请求示例

curl -X POST /api/v1/favorites \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"poemId":"1","poemTitle":"静夜思","poemAuthor":"李白","poemDynasty":"唐"}'

响应示例

{ "success": true, "data": { "id": "...", "poemId": "1", "poemTitle": "静夜思", "poemAuthor": "李白", ... } }

DELETE/api/v1/favorites/:id🔒 需认证取消收藏（:id 为 poemId）

请求示例

curl -X DELETE /api/v1/favorites/1 -H "Authorization: Bearer <token>"

响应示例

{ "success": true, "data": null }

GET/api/v1/favorites/sync🔒 需认证收藏同步 — 返回全部收藏 + syncToken（updatedAt 时间戳），用于多端同步

请求示例

curl /api/v1/favorites/sync -H "Authorization: Bearer <token>"

响应示例

{
  "success": true,
  "data": {
    "favorites": [ { "id": "...", "poemId": "1", "poemTitle": "静夜思", "createdAt": "...", "updatedAt": "..." } ],
    "syncToken": "2026-07-23T10:30:00.000Z",
    "total": 5
  }
}

阅读历史接口 🔒

GET/api/v1/history🔒 需认证获取阅读历史（按时间倒序，最近 50 条）

请求示例

curl /api/v1/history -H "Authorization: Bearer <token>"

响应示例

{ "success": true, "data": { "records": [ { "id": "...", "poemId": "1", "poemTitle": "静夜思", "poemAuthor": "李白", "poemDynasty": "唐", "readAt": "2026-07-22T..." } ], "total": 1 } }

POST/api/v1/history🔒 需认证记录阅读（每次阅读创建新记录）

参数

名称	类型	说明
poemId	`string`	诗词 ID（必填）
poemTitle	`string`	诗词标题（必填）
poemAuthor	`string`	作者
poemDynasty	`string`	朝代

请求示例

curl -X POST /api/v1/history \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"poemId":"1","poemTitle":"静夜思","poemAuthor":"李白"}'

响应示例

{ "success": true, "data": { "id": "...", "poemId": "1", "poemTitle": "静夜思", "readAt": "..." } }

阅读统计接口

GET/api/v1/stats/reading阅读统计 — 全局热门诗词/作者排行 + 近7日每日阅读量（无需认证，可做首页数据看板）

请求示例

curl /api/v1/stats/reading

响应示例

{
  "success": true,
  "data": {
    "totalReads": 12580,
    "totalPoems": 3200,
    "topPoems": [
      { "poemId": "1", "poemTitle": "静夜思", "count": 523 }
    ],
    "topAuthors": [
      { "author": "李白", "count": 1890 }
    ],
    "readsByDay": [
      { "date": "2026-07-17", "count": 120 },
      { "date": "2026-07-18", "count": 145 }
    ]
  }
}

📖

加载中...