Skip to content

语句接口

简介

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

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

该接口也是我们(萌创团队)自 2016 年以来稳定提供的接口。目前接口经历了这些变化:

  • 2016 初版接口,实验性提供。占用域名:api.hitokoto.cnsslapi.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 停用了网易云插件。
如您仍有此需求,请:

时间规划

时间版本影响接口调整技术栈
2018 年 6 月测试api.hitokoto.cnsslapi.hitokoto.cn接口重定向至 v1 接口。老接口将不做可用性保证。PHP
2018 年7 月v1v1.hitokoto.cnv1 接口锁定功能结构,若无重要原因将不会增减功能。接口将稳定存在直至 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.cnHTTPSAny2全球
international.v1.hitokoto.cnHTTPSAny20(含缓存*)海外

请注意:一言域名已加入 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 停用了网易云插件。如您仍有此需求,建议如下方案:

本文档遵循 MIT 协议