随机诗词API最小可运行示例：curl接入与参数详解

适用场景随机诗词API适合需要展示或引用古典诗词的应用场景例如个人博客或网站侧边栏的每日诗词轮播智能硬件如桌面摆件、电子贺卡的文本内容源游戏或社交应用中的文化彩蛋前端开发人员调试UI布局时填充占位文本语言学习类App的古诗词展示模块由于接口仅返回一首诗词包含标题、作者、正文并且支持按主题筛选开发者可以快速实现“今日推荐”、“分主题诗词墙”等功能而无需自建诗词数据库。接口能力边界在接入前需要了解以下限制请求方法仅支持 POSTQPS 限制5 次/秒。如果并发请求超过此限制服务端会返回 429 状态码建议在客户端加入指数退避重试逻辑。主题筛选10 种抒情/四季/山水/天气/人物/生活/节日/动物/植物/食物。不传 type 时返回完全随机诗词。数据量接口不会返回诗词总数或分页信息每次仅返回一首。如需获取多首需多次请求并注意限流。鉴权方式必须携带 API Key通过请求头X-API-Key传递。鉴权方式调用接口前需要先获取 API Key。每个账号或应用拥有唯一的 Key用于身份验证和调用量统计。获取方式请参考官方文档参见文末链接。鉴权信息通过 HTTP 请求头传递X-API-Key: YOUR_API_KEY Content-Type: application/json如果未提供或提供无效的 Key接口会返回 403 错误。最小可运行 curl 示例示例一获取随机诗词不指定主题这是最简单的调用方式不传请求体接口返回任意一首古诗词curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ https://v1.apizero.cn/api/shici注意请将$APIZERO_API_KEY替换为你的真实 API Key或者直接写入字符串如-H X-API-Key: abc123。如果在 Windows 命令行下运行请去掉\续行符并将内容写在同一行。示例二按主题筛选例如“山水”在请求体中指定type字段为目标主题的 slugcurl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {type:shanshui} \ https://v1.apizero.cn/api/shici支持的 10 种主题 slug 列表主题slug抒情shuqing四季siji山水shanshui天气tianqi人物renwu生活shenghuo节日jieri动物dongwu植物zhiwu食物shiwu示例三获取主题类型列表如果调用前不确定当前支持哪些主题可以设置action参数为types接口会返回类型列表且该操作不消耗调用额度curl -sS -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {action:types} \ https://v1.apizero.cn/api/shici返回示例{ code: 200, message: success, data: [ {slug: shuqing, name: 抒情}, {slug: siji, name: 四季}, ... ] }Python 代码接入示例以下使用requests库演示如何调用接口并解析返回的诗词内容import requests import json API_URL https://v1.apizero.cn/api/shici API_KEY YOUR_API_KEY # 替换为你的真实 Key def get_random_poem(type_slug: str None) - dict: 获取随机诗词可选按主题筛选 headers { X-API-Key: API_KEY, Content-Type: application/json } body {} if type_slug: body[type] type_slug resp requests.post(API_URL, headersheaders, jsonbody) resp.raise_for_status() # 非2xx时抛出异常 return resp.json() # 示例获取一首“山水”主题的诗词 result get_random_poem(shanshui) print(json.dumps(result, ensure_asciiFalse, indent2))注意生产环境中应将 API Key 存储在环境变量或配置文件中避免硬编码。返回字段详解成功的响应始终包含以下字段{ code: 200, message: success, data: { title: 题西林壁, author: 苏轼, content: 横看成岭侧成峰远近高低各不同。不识庐山真面目只缘身在此山中。, type: shanshui, dynasty: 宋代 } }字段类型说明codeinteger状态码200 表示成功messagestring状态描述dataobject诗词数据包含以下子字段data.titlestring诗词标题data.authorstring作者姓名data.contentstring诗词正文多句用换行符\n分隔data.typestring请求时指定的 type若未指定则为randomdata.dynastystring朝代如“唐代”、“宋代”当请求actiontypes时data变为数组包含每个主题的 slug 和名称。常见错误及处理HTTP 状态码code含义排查方向400400请求体格式错误或缺少必要字段检查 JSON 是否合法、type 值是否为支持的 slug403403API Key 无效或未提供确认X-API-Key头是否携带且正确429429请求频率超过 QPS 限制5次/秒加入延时或使用重试机制如指数退避500500服务端内部错误稍后重试若持续出现请联系技术支持对于 429 错误建议实现如下退避逻辑Python 伪代码import time import requests max_retries 3 for attempt in range(max_retries): resp requests.post(API_URL, headersheaders, jsonbody) if resp.status_code 429: wait 2 ** attempt time.sleep(wait) continue resp.raise_for_status() break工程化注意事项缓存策略如果页面需要反复展示同一主题的诗词例如每天一次建议将结果缓存到内存或 Redis 中设置 TTL 为 1 小时以上减少对接口的调用压力。API Key 安全前端代码中不应直接暴露 API Key。应通过后端代理转发请求或使用 Serverless Function 作为中间层。QPS 规划若有多处业务同时调用需确保总调用频率 ≤ 5 QPS。可以在请求前加上time.sleep(0.2)来平摊请求。网络超时设置建议在 HTTP 客户端设置合理的超时时间如 5 秒避免长时间阻塞。错误回退当接口返回非 200 时应降级显示备选诗词如从本地预置列表中随机选取保证用户体验。日志记录记录请求耗时、返回的 code 和 poem title便于后期排查异常和统计调用量。参考文档随机诗词 API 文档页原始 Markdown 文档参数细节本文提到的所有 slug 和参数说明均以官方文档为准如有更新请以最新版文档为准。