### GET https://v2.jinrishici.com/one.json Source: https://www.jinrishici.com/doc 浏览器直接访问接口，适用于浏览器插件和 IOS 捷径。该接口会返回一首推荐诗词及其相关信息，并自动发送一个等效于 Token 的 Cookies。注意此接口仅适用于浏览器直接访问，不适用于网站调用。 ```APIDOC ## [GET] https://v2.jinrishici.com/one.json ### Description 浏览器直接访问接口，适用于浏览器插件和 IOS 捷径。该接口会返回一首推荐诗词及其相关信息，并自动发送一个等效于 Token 的 Cookies。注意此接口仅适用于浏览器直接访问，不适用于网站调用。 ### Method GET ### Endpoint https://v2.jinrishici.com/one.json ### Response #### Success Response (200) - **status** (string) - 固定为 "success" - **data** (object) - 包含推荐诗词的详细信息 - **id** (string) - 诗词的唯一标识 - **content** (string) - 推荐的诗句 - **popularity** (number) - 诗句的流行度评价 - **origin** (object) - 源诗信息 - **title** (string) - 诗名 - **dynasty** (string) - 朝代 - **author** (string) - 作者 - **content** (array) - 诗的全文 - **translate** (array) - 整诗翻译（部分诗词有） - **matchTags** (array) - 与用户相关的标签 - **recommendedReason** (string) - 推荐原因（暂未支持） - **cacheAt** (string) - 缓存时间 - **token** (string) - 当前用户的 token - **ipAddress** (string) - 当前用户的 IP 地址 #### Response Example { "status": "success", "data": { "id": "5b8b9572e116fb3714e6faba", "content": "君问归期未有期，巴山夜雨涨秋池。", "popularity": 1170000, "origin": { "title": "夜雨寄北", "dynasty": "唐代", "author": "李商隐", "content": [ "君问归期未有期，巴山夜雨涨秋池。", "何当共剪西窗烛，却话巴山夜雨时。" ], "translate": [ "您问归期，归期实难说准，巴山连夜暴雨，涨满秋池。", "何时归去，共剪西窗烛花，当面诉说，巴山夜雨况味。" ] }, "matchTags": [ "秋", "晚上" ], "recommendedReason": "", "cacheAt": "2018-09-17T21:18:44.693645" }, "token": "6453911a-9ad7-457e-9b9d-c21011b85a0c", "ipAddress": "162.248.93.154" } #### Error Response - **status** (string) - 固定为 "error" - **errCode** (number) - 错误码 - **errMessage** (string) - 错误信息 #### Error Codes - **1001** - 内部服务器错误，HTTP状态码 500 - **1002** - API路径不对，HTTP状态码 404 - **2002** - Token不是服务器签发，HTTP状态码 400 - **2003** - IP超过每日新用户限制，HTTP状态码 400 #### Error Response Example { "status": "error", "errCode": 2001, "errMessage": "No matching handler" } ``` -------------------------------- ### GET https://v2.jinrishici.com/sentence Source: https://www.jinrishici.com/doc 获取诗词推荐。需要在 HTTP 请求头中指定 Token（X-User-Token），返回结果为 JSON 格式的诗词数据。 ```APIDOC ## [GET] https://v2.jinrishici.com/sentence ### Description 获取诗词推荐。需要在 HTTP 请求头中指定 Token（X-User-Token），返回结果为 JSON 格式的诗词数据。 ### Method GET ### Endpoint https://v2.jinrishici.com/sentence ### Parameters #### Headers - **X-User-Token** (string) - Required - 用户 Token，用于标识用户 ### Response #### Success Response (200) 返回结果格式详见接口返回结果格式文档。 #### Response Example （未提供具体示例） ``` -------------------------------- ### GET https://v2.jinrishici.com/info Source: https://www.jinrishici.com/doc 高级测试接口，用于验证接口安装是否正确。可附带 Token 以获取用户相关信息，返回结果包含 Token、IP、地区、天气、标签等信息。 ```APIDOC ## [GET] https://v2.jinrishici.com/info ### Description 高级测试接口，用于验证接口安装是否正确。可附带 Token 以获取用户相关信息，返回结果包含 Token、IP、地区、天气、标签等信息。 ### Method GET ### Endpoint https://v2.jinrishici.com/info ### Parameters #### Headers - **X-User-Token** (string) - Optional - 用户 Token，用于标识用户 ### Response #### Success Response (200) - **status** (string) - 请求状态，成功时为 "success" - **data** (object) - 包含以下字段： - **token** (string) - 当前使用的 Token - **ip** (string) - 用户 IP 地址 - **region** (string) - 用户所在地区 - **weatherData** (object) - 天气数据，包含温度、风向、风力、湿度、更新时间、天气、能见度、降雨量、PM2.5 - **tags** (array) - 诗词标签列表 - **beijingTime** (string) - 北京时间 #### Response Example { "status": "success", "data": { "token": "5894fcba-0f9b-435e-b460-bb02d19b8974", "ip": "215.17.40.175", "region": "广东|深圳", "weatherData": { "temperature": 26, "windDirection": "东风", "windPower": 1, "humidity": 91, "updateTime": "23:10", "weather": "雨", "visibility": "33.43km", "rainfall": 0, "pm25": 23 }, "tags": [ "桂花", "华南", "雨", "秋", "晚上" ], "beijingTime": "2018-09-17T23:47:48.194228" } } ``` -------------------------------- ### GET https://v2.jinrishici.com/token Source: https://www.jinrishici.com/doc 获取用于鉴别用户的 Token，Token 永久有效。调用后需将返回的 Token 存储在长效存储中（如 localStorage），后续请求需附带该 Token。 ```APIDOC ## [GET] https://v2.jinrishici.com/token ### Description 获取用于鉴别用户的 Token，Token 永久有效。调用后需将返回的 Token 存储在长效存储中（如 localStorage），后续请求需附带该 Token。 ### Method GET ### Endpoint https://v2.jinrishici.com/token ### Response #### Success Response (200) - **status** (string) - 请求状态，成功时为 "success" - **data** (string) - 获取的 Token 值 #### Response Example { "status": "success", "data": "RgU1rBKtLym/MhhYIXs42WNoqLyZeXY3EkAcDNrcfKkzj8ILIsAP1Hx0NGhdOO1I" } ``` -------------------------------- ### GET /one.svg Source: https://www.jinrishici.com/doc 获取今日诗词图片，支持通过查询参数自定义字体大小、间距和颜色。该接口仅限在网站中调用，不推荐在 APP 中使用。 ```APIDOC ## GET /one.svg ### Description 获取今日诗词图片，支持通过查询参数自定义字体大小、间距和颜色。该接口仅限在网站中调用，不推荐在 APP 中使用。 ### Method GET ### Endpoint https://v2.jinrishici.com/one.svg ### Parameters #### Query Parameters - **font-size** (integer) - Optional - 字体大小(px)，默认值 20，合法范围 [8,50] - **spacing** (number) - Optional - 间距(px)，默认值 1.5，合法范围 [0,30] - **color** (string) - Optional - 颜色，默认值 black，合法值为颜色英文单词 ### Request Example https://v2.jinrishici.com/one.svg?font-size=20&spacing=2&color=blue ### Response #### Success Response (200) 返回 SVG 图片。 #### Response Example （图片内容） ``` -------------------------------- ### NPM SDK：带错误处理的 load 调用 Source: https://www.jinrishici.com/doc 可传入第二个错误处理函数，处理加载错误时的情况。 ```javascript const jinrishici = require('jinrishici'); jinrishici.load(result => { console.log(result); }, errData => { console.log(err); }); ``` -------------------------------- ### NPM 安装今日诗词 SDK Source: https://www.jinrishici.com/doc 通过 npm 安装 jinrishici 包，仅支持浏览器环境，不支持 Node 和服务器渲染。 ```bash npm -i jinrishici --save ``` -------------------------------- ### 微信小程序 SDK：调用加载函数 Source: https://www.jinrishici.com/doc 在 onLoad 或其他位置调用 jinrishici.load，传入回调函数处理返回结果。 ```javascript jinrishici.load(result => { // 下面是处理逻辑示例 console.log(result) this.setData({"jinrishici": result.data.content}) }) ``` -------------------------------- ### NPM SDK：引入并调用 load 函数 Source: https://www.jinrishici.com/doc 在页面启动函数中引入 SDK 并调用 load，传入处理结果的函数。 ```javascript const jinrishici = require('jinrishici'); jinrishici.load(result => { console.log(result); }); ``` -------------------------------- ### 微信小程序 SDK：引用 SDK 文件 Source: https://www.jinrishici.com/doc 在需要调用 SDK 的 Page 的 JS 文件顶部引用，注意文件夹深度确保路径正确。 ```javascript const jinrishici = require('../../utils/jinrishici.js') ``` -------------------------------- ### 微信小程序 SDK：添加 API 地址到白名单 Source: https://www.jinrishici.com/doc 在微信后台配置请求白名单，允许小程序访问今日诗词 API 地址。 ```text https://v2.jinrishici.com ``` -------------------------------- ### 安卓 SDK：初始化方法 Source: https://www.jinrishici.com/doc 在调用接口前初始化 SharedPreference 存储，两种方式任选其一；控件形式调用可跳过。 ```java //以下两种初始化方式任选一种即可 JinrishiciFactory.init(getContext()); JinrishiciClient.getInstance().init(getContext()); ``` -------------------------------- ### JS-SDK 高级加载函数调用 Source: https://www.jinrishici.com/doc 使用 jinrishici.load 函数传入回调以获取诗词数据，适用于需要自定义处理逻辑的场景。请确保在调用前已引入 SDK 文件，且不要将标签 ID 设置为 jinrishici-sentence 以避免自动加载。 ```html ``` -------------------------------- ### 安卓 SDK：Gradle 安装依赖 Source: https://www.jinrishici.com/doc 通过 Gradle 添加 android-sdk 依赖，版本 1.5。 ```groovy implementation 'com.jinrishici:android-sdk:1.5' ``` -------------------------------- ### 安卓 SDK：异步获取诗词 Source: https://www.jinrishici.com/doc 使用 JinrishiciCallback 异步获取诗词，在 done 中处理成功逻辑，在 error 中处理错误。 ```java JinrishiciClient client = JinrishiciClient.getInstance(); client.getOneSentenceBackground(new JinrishiciCallback() { @Override public void done(PoetySentence poetySentence) { //TODO do something //在这里进行你的逻辑处理 } @Override public void error(JinrishiciRuntimeException e) { Log.w(TAG, "error: code = " + e.getCode() + " message = " + e.getMessage()); //TODO do something else } }); ``` -------------------------------- ### 安卓 SDK：同步获取诗词 Source: https://www.jinrishici.com/doc 同步方法，请求出错时抛出 JinrishiciRuntimeException，需自行捕获；与异步方法二选一。 ```java PoetySentence poetySentence = JinrishiciClient.getInstance().getOneSentence(); ``` -------------------------------- ### Markdown 格式调用 Source: https://www.jinrishici.com/doc 在 Markdown 文档中嵌入今日诗词图片。 ```markdown ![今日诗词](https://v2.jinrishici.com/one.svg) ``` -------------------------------- ### 协议占位符 Source: https://www.jinrishici.com/doc 协议文档中的空行占位符。 ```text 　 ``` -------------------------------- ### Vue 中使用 NPM SDK 的示例 Source: https://www.jinrishici.com/doc 在 Vue 的 mounted 钩子中调用 load 方法，展示加载诗词并设置到 data 的示例。 ```javascript methods: { loadSentence: function() { jinrishici.load(result => { this.msg = result.data.content }, err => { console.log("test"); }) } }, mounted: function(){this.loadSentence()} ``` -------------------------------- ### 安卓 SDK：Maven 安装依赖 Source: https://www.jinrishici.com/doc 通过 Maven 添加 android-sdk 依赖，版本 1.5。 ```xml com.jinrishici android-sdk 1.5 pom ``` -------------------------------- ### 添加今日诗词 API 友情链接 Source: https://www.jinrishici.com/doc 在您的网站中添加此 HTML 代码以支持今日诗词 API 的持续发展。 ```html 今日诗词 API ``` -------------------------------- ### 安卓 SDK：自定义控件 JinrishiciTextView Source: https://www.jinrishici.com/doc 将控件添加进布局，自动请求数据并展示，无需手动初始化；可像 TextView 一样设置属性。 ```xml ``` -------------------------------- ### 网站快速安装通用代码 Source: https://www.jinrishici.com/doc 在 HTML 中放置指定 ID 的 span 标签并引入 SDK，SDK 会自动将内容替换为诗词。 ```html 正在加载今日诗词.... ``` -------------------------------- ### 正确返回JSON示例 Source: https://www.jinrishici.com/doc 接口正常返回的JSON格式，包含status、data、token和ipAddress字段。data.content为核心诗句，data.matchTags为相关标签，data.cacheAt为缓存时间（约10分钟更新），data.popularity为流行度，data.origin为源诗信息，data.origin.translate为整诗翻译（部分诗词有）。 ```json { "status": "success", "data": { "id": "5b8b9572e116fb3714e6faba", "content": "君问归期未有期，巴山夜雨涨秋池。", "popularity": 1170000, "origin": { "title": "夜雨寄北", "dynasty": "唐代", "author": "李商隐", "content": [ "君问归期未有期，巴山夜雨涨秋池。", "何当共剪西窗烛，却话巴山夜雨时。" ], "translate": [ "您问归期，归期实难说准，巴山连夜暴雨，涨满秋池。", "何时归去，共剪西窗烛花，当面诉说，巴山夜雨况味。" ] }, "matchTags": [ "秋", "晚上" ], "recommendedReason": "", "cacheAt": "2018-09-17T21:18:44.693645" }, "token": "6453911a-9ad7-457e-9b9d-c21011b85a0c", "ipAddress": "162.248.93.154" } ``` -------------------------------- ### 自定义图片参数调用 Source: https://www.jinrishici.com/doc 通过 URL 参数自定义字体大小、间距和颜色。 ```text https://v2.jinrishici.com/one.svg?font-size=20&spacing=2&color=blue ``` -------------------------------- ### HTML 格式调用 Source: https://www.jinrishici.com/doc 在 HTML 页面中嵌入今日诗词图片。 ```html 今日诗词 ``` -------------------------------- ### 博客与论坛集成示例 Source: https://www.jinrishici.com/doc 在博客或论坛模板（如 footer.php）中集成快速安装代码的示例。请确保代码放置在 PHP 标签之外。 ```html ``` -------------------------------- ### 图片调用地址 Source: https://www.jinrishici.com/doc 直接访问的图片调用地址。 ```text https://v2.jinrishici.com/one.svg ``` -------------------------------- ### 居中显示 HTML 调用 Source: https://www.jinrishici.com/doc 使用内联样式使图片在 DIV 中居中且不溢出。 ```html 今日诗词 ``` -------------------------------- ### 高级版诗词展示示例 Source: https://www.jinrishici.com/doc 一个完整的高级使用示例，展示如何将诗词内容及作者、朝代等信息渲染到指定的 HTML 元素中。 ```html
``` -------------------------------- ### 错误返回JSON示例 Source: https://www.jinrishici.com/doc 接口错误返回的JSON格式，包含status、errCode和errMessage字段。错误码包括1001（内部服务器错误，HTTP 500）、1002（API路径不对，HTTP 404）、2002（Token不是服务器签发，HTTP 400）、2003（IP超过每日新用户限制，HTTP 400）。 ```json { "status": "error", "errCode": 2001, "errMessage": "No matching handler" } ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.