📖
加载中...
📖
加载中...
Poetry Gateway · 统一响应格式 · RESTful API
成功 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)
/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
}
}/api/v1/discover发现页：近期诗词 + 朝代列表 + 体裁列表请求示例
curl /api/v1/discover
响应示例
{
"success": true,
"data": {
"recentPoems": [ ... ],
"dynasties": [ { "id": 1, "name": "唐" }, ... ],
"types": [ { "id": 1, "name": "五言绝句" }, ... ]
}
}/api/v1/categories分类聚合：所有朝代 + 所有体裁请求示例
curl /api/v1/categories
响应示例
{
"success": true,
"data": {
"dynasties": [ { "id": 1, "name": "唐" }, ... ],
"types": [ { "id": 10, "name": "五言绝句" }, ... ]
}
}/api/v1/recommend为你推荐请求示例
curl /api/v1/recommend
响应示例
{
"success": true,
"data": {
"poems": [ ... ],
"reason": "为你精选"
}
}/api/v1/quote每日一句：随机取一句诗词 + 出处请求示例
curl /api/v1/quote
响应示例
{
"success": true,
"data": {
"content": "床前明月光，疑是地上霜",
"author": "李白",
"source": "静夜思"
}
}/api/v1/config客户端配置：版本号、功能开关、Banner请求示例
curl /api/v1/config
响应示例
{
"success": true,
"data": {
"version": "1.0.0",
"bannerUrl": null,
"features": { "aiAnalysis": true, "aiAsk": true, "favorites": true, ... }
}
}/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
}
}/api/v1/poems/:id诗词详情请求示例
curl /api/v1/poems/1
响应示例
{
"success": true,
"data": {
"id": 1, "title": "静夜思", "content": "床前明月光，疑是地上霜。举头望明月，低头思故乡。",
"author": "李白", "dynasty": "唐", "type": "五言绝句"
}
}/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": "李白", ... } }/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
}
}/api/v1/authors/:id作者详情请求示例
curl /api/v1/authors/1
响应示例
{ "success": true, "data": { "id": 1, "name": "李白", "dynasty": "唐", "description": "字太白...", "poemCount": 896 } }/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": "静夜思"
}
}/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": ["思乡之情", "孤寂之感"]
}
}/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": "李白与杜甫是唐代诗坛的双子星座..." } }/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": ["床：指井栏或坐具，非现代意义的床"]
}
}/api/v1/user/register用户注册参数
| 名称 | 类型 | 说明 |
|---|---|---|
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": "诗词爱好者" } } }/api/v1/user/login用户登录，返回 JWT Token参数
| 名称 | 类型 | 说明 |
|---|---|---|
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..." } } }/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": "..." } }/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": "新昵称", ... } }/api/v1/favorites🔒 需认证获取收藏列表请求示例
curl /api/v1/favorites -H "Authorization: Bearer <token>"
响应示例
{ "success": true, "data": { "favorites": [ { "id": "...", "poemId": "1", "poemTitle": "静夜思", "poemAuthor": "李白", "poemDynasty": "唐", "createdAt": "..." } ], "total": 1 } }/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": "李白", ... } }/api/v1/favorites/:id🔒 需认证取消收藏（:id 为 poemId）请求示例
curl -X DELETE /api/v1/favorites/1 -H "Authorization: Bearer <token>"
响应示例
{ "success": true, "data": null }/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 } }/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": "..." } }