一言开发者中心语句接口
简介
动漫也好、小说也好、网络也好，不论在哪里，我们总会看到有那么一两个句子能穿透你的心。我们把这些句子汇聚起来，形成一言网络，以传递更多的感动。如果可以，我们希望我们没有停止服务的那一天。
简单来说，一言指的就是一句话，可以是动漫中的台词，也可以是网络上的各种小段子。 或是感动，或是开心，有或是单纯的回忆。来到这里，留下你所喜欢的那一句句话，与大家分享，这就是一言存在的目的。
该接口也是我们（萌创团队）自 2016 年以来稳定提供的接口。目前接口经历了这些变化：
- 2016 初版接口，实验性提供。占用域名：
api.hitokoto.cn和sslapi.hitokoto.cn - 2018 v1 接口，开始稳定提供。占用域名：
v1.hitokoto.cn- 2018.02 测试状态统计
- 2018.03 测试网易云
- 2018.04 开始分布式部署
- 2019.10 DogeCloud 开始提供赞助，成为我们的顶级赞助商。
- 2020.01 恢复使用部分弃用字段，句子启用追踪 UUID，为主站重构做基础
- 2020.06 发布
1.5.0，加入句子区间功能，重构大部分基础模块，优化性能，修复问题
请注意：
由于网易云接口被过度滥用，我们于 2022.11.18 停用了网易云插件。
如您仍有此需求，请：
- 自行部署接口，参考 接口部署。
- 使用 NeteaseCloudMusicApi 提供的接口，参考 NeteaseCloudMusicApi
时间规划
| 时间 | 版本 | 影响接口 | 调整 | 技术栈 |
|---|---|---|---|---|
| 2018 年 6 月 | 测试 | api.hitokoto.cn 和 sslapi.hitokoto.cn | 接口重定向至 v1 接口。老接口将不做可用性保证。 | PHP |
| 2018 年7 月 | v1 | v1.hitokoto.cn | v1 接口锁定功能结构，若无重要原因将不会增减功能。接口将稳定存在直至 v2 上线后一年。 | Node.js 和 Docker |
| 预计 2023 年 | v2 | 未知 | 上线 v2 接口 | Node.js，Go 或者 Swoole |
目前 v1 接口已进入功能锁定阶段。 如果你有什么想法或建议， 可以在 功能申请表 中提出。
由于一言目前属于公益性运营，为了保证资源的公平利用和不过度消耗公益资金，我们会定期的屏蔽某些大流量的站点。若您的站点的流量较大，您需要提前联系我们获得授权后再开始使用。对于超过阈值的站点，我们有可能会通过一定途径（例如邮件）等方式联系您，若 24 小时无回应则域名将暂时进入黑名单。
考虑到大家的实际应用需求，我们在 爱发电 上架了一个可以提高请求限制的赞助选项，有需要可以前往了解。
接口说明
请注意： 语句接口的后端已经开源，并允许自行部署，效果我们提供的服务完全一致。同时，我们的语句库在遵守使用协议的情况下允许任何人免费使用。
一言是一个公益性服务，我们没有具备充足的资金和资源应对超高并发的请求。如果您的站点流量较大、请求数较多，从稳定性、可控性考虑，我们都建议您自行部署 API，或在程序中使用缓存减轻请求压力。
详细的部署指南请参考：接口部署
详细的语句接口后端更新信息请参考：https://github.com/hitokoto-osc/hitokoto-api/releases
语句库使用指南：https://sentences-bundle.hitokoto.cn
为了一言的长久发展，我们恳求您在使用一言服务的同时 尽可能 地加入一言的链接（如：添加友情链接，为一言文本附加超链接）。
请求地址
| 地址 | 协议 | 方法 | QPS 限制 | 线路 |
|---|---|---|---|---|
v1.hitokoto.cn | HTTPS | Any | 2 | 全球 |
international.v1.hitokoto.cn | HTTPS | Any | 20(含缓存*) | 海外 |
请注意：一言域名已加入 HSTS 预加载计划，所有请求一律以 HTTPS 方法进行。
国际站当前因持续的流量、负载和攻击题，开启了缓存，缓存2s过期。实际效果：同一个地区、线路、使用同一参数的访问者短时间内得到的句子是一致的。这样可以有效的降低运算服务器的负载，并提高用户体验，也可以反爬虫。 目前不确定该规则国内站是否一并开启，将根据后期运营情况确定。 可以确定的一点：我们不欢迎爬虫通过不断刷新接口爬取句子数据库。一言接口使用的句子数据库已全部公开，可查看[语句库]https://sentences-bundle.hitokoto.cn进行使用。
请求参数
| 参数 | 值 | 可选 | 说明 |
|---|---|---|---|
| c | 见后表 | 是 | 句子类型 |
| encode | 见后表 | 是 | 返回编码 |
| charset | 见后表 | 是 | 字符集 |
| callback | 如：moe | 是 | 调用的异步函数 |
| select | 默认：.hitokoto | 是 | 选择器。配合 encode=js 使用 |
| min_length | 默认：0 | 是 | 返回句子的最小长度（包含） |
| max_length | 默认：30 | 是 | 返回句子的最大长度（包含） |
句子类型（参数）
| 参数 | 说明 |
|---|---|
| a | 动画 |
| b | 漫画 |
| c | 游戏 |
| d | 文学 |
| e | 原创 |
| f | 来自网络 |
| g | 其他 |
| h | 影视 |
| i | 诗词 |
| j | 网易云 |
| k | 哲学 |
| l | 抖机灵 |
| 其他 | 作为 动画 类型处理 |
可选择多个分类，例如：
?c=a&c=c
返回编码（参数）
| 参数 | 说明 |
|---|---|
| text | 返回纯洁文本 |
| json | 返回格式化后的 JSON 文本 |
| js | 返回指定选择器的同步调用函数。默认选择器为：.hitokoto |
| 其他 | 返回格式化后的 JSON 文本 |
字符集（参数）
| 参数 | 说明 |
|---|---|
| utf-8 | 返回 utf-8 编码的内容 |
| gbk | 返回 gbk 编码的内容。不支持与异步函数同用 |
| 其他 | 返回 utf-8 编码的内容 |
返回信息
| 返回参数名称 | 描述 |
|---|---|
| id | 一言标识 |
| hitokoto | 一言正文。编码方式 unicode。使用 utf-8。 |
| type | 类型。请参考第三节参数的表格 |
| from | 一言的出处 |
| from_who | 一言的作者 |
| creator | 添加者 |
| creator_uid | 添加者用户标识 |
| reviewer | 审核员标识 |
| uuid | 一言唯一标识；可以链接到 https://hitokoto.cn?uuid=[uuid] 查看这个一言的完整信息 |
| commit_from | 提交方式 |
| created_at | 添加时间 |
| length | 句子长度 |
扩展
- 网易云 API，当前相关文档尚未制作，可以先参考 介绍
- 请注意，由于网易云接口被过度滥用，现网接口于
2022.11.18停用了网易云插件。如您仍有此需求，建议如下方案：- 自行部署接口，参考 接口部署。
- 使用 NeteaseCloudMusicApi 提供的接口，参考 NeteaseCloudMusicApi
- 请注意，由于网易云接口被过度滥用，现网接口于