# 语句接口

# 简介

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

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

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

  • 2016 初版接口,实验性提供。占用域名:api.hitokoto.cnsslapi.hitokoto.cn
  • 2018 v1 接口,开始稳定提供。占用域名: v1.hitokoto.cn
    • 2018.02 测试状态统计
    • 2018.03 测试网易云
    • 2018.04 开始分布式部署
    • 2019.10 DogeCloud 开始提供赞助,成为我们的顶级赞助商。
    • 2020.01 恢复使用部分弃用字段,句子启用追踪 UUID,为主站重构做基础

# 时间规划

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

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

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

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

# 接口说明

# 请求地址

地址 协议 方法 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 使用

# 句子类型(参数)

参数 说明
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] 查看这个一言的完整信息
created_at 添加时间

# 扩展

  • 网易云 API, 目前文档尚未制作,可以先参考 Github
    • 由于网易云最近封锁严重,建议自行搭建。
最后更新: 4/12/2020, 12:09:51 AM