语句接口

简介

动漫也好、小说也好、网络也好，不论在哪里，我们总会看到有那么一两个句子能穿透你的心。我们把这些句子汇聚起来，形成一言网络，以传递更多的感动。如果可以，我们希望我们没有停止服务的那一天。

简单来说，一言指的就是一句话，可以是动漫中的台词，也可以是网络上的各种小段子。 或是感动，或是开心，有或是单纯的回忆。来到这里，留下你所喜欢的那一句句话，与大家分享，这就是一言存在的目的。

该接口也是我们（萌创团队）自 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，加入句子区间功能，重构大部分基础模块，优化性能，修复问题

时间规划

时间 版本 影响接口 调整 技术栈
2018 年 6 月 测试 api.hitokoto.cn 和 sslapi.hitokoto.cn 接口重定向至 v1 接口。老接口将不做可用性保证。 PHP
2018 年7 月 v1 v1.hitokoto.cn v1 接口锁定功能结构，若无重要原因将不会增减功能。接口将稳定存在直至 v2 上线后一年。 Node.js 和 Docker
预计 2021 年 v2 未知 上线 v2 接口 Node.js，Go 或者 Swoole

目前 v1 接口已进入功能锁定阶段。 如果你有什么想法或建议， 可以在 功能申请表 中提出。

由于一言目前属于公益性运营，为了保证资源的公平利用和不过度消耗公益资金，我们会定期的屏蔽某些大流量的站点。若您的站点的流量较大，您需要提前联系我们获得授权后再开始使用。对于超过阈值的站点，我们有可能会通过一定途径（例如邮件）等方式联系您，若 24 小时无回应则域名将暂时进入黑名单。

考虑到大家的实际应用需求，我们在 爱发电 上架了一个可以提高请求限制的赞助选项，有需要可以前往了解。

接口说明

请注意： 我们于 2020 年 6 月 15 日发布了语句接口的 1.5.0 版本，此版本允许你查找范围区间，允许你部署自己的接口服务（与我们提供的一致）。 详细的更新信息请参考：https://github.com/hitokoto-osc/hitokoto-api/releases

为了一言的长久发展，我们恳求您在使用一言服务得同时 尽可能 得加入一言的链接（如：添加友情链接，为一言文本附加超链接）。

请求地址

地址 协议 方法 QPS 限制 线路
v1.hitokoto.cn HTTPS Any 3.5 全球
international.v1.hitokoto.cn HTTPS Any 10 国外

请注意：一言域名已加入 HSTS 预加载计划，所有请求一律以 HTTPS 方法进行。

请求参数

参数 值 可选 说明
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， 目前文档尚未制作，可以先参考 介绍
    • 由于网易云最近封锁严重，建议自行搭建。