关于一言API的使用
2020-05-04 / CHINQ / / 9 min. read

本文章摘抄自一言官方 API 文档 https://developer.hitokoto.cn/

语句接口

简介

动漫也好、小说也好、网络也好,不论在哪里,我们总会看到有那么一两个句子能穿透你的心。我们把这些句子汇聚起来,形成一言网络,以传递更多的感动。如果可以,我们希望我们没有停止服务的那一天
简单来说,一言指的就是一句话,可以是动漫中的台词,也可以是网络上的各种小段子。 或是感动,或是开心,有或是单纯的回忆。来到这里,留下你所喜欢的那一句句话,与大家分享,这就是一言存在的目的

该接口也是我们(萌创团队)自 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,为主站重构做基础

    接口说明

    请求地址

    地址 协议 方法 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 添加时间

    使用示例

    https://v1.hitokoto.cn/ (从7种分类中随机抽取)
    https://v1.hitokoto.cn/?c=b (请求获得一个分类是漫画的句子)
    https://v1.hitokoto.cn/?c=f&encode=text (请求获得一个来自网络的句子,并以纯文本格式输出)

    网页

    请注意:
    本例所有写法(除 XMLHttpRequest 示例)使用 ES6 语法。如果您想考虑兼容非现代浏览器(如:IE),需要您自行转换。
    <p id="hitokoto">:D 获取中...</p>
    <!-- 以下写法,选取一种即可 -->
    <!-- 现代写法,推荐(不支持 IE) -->
    <script>
    fetch('https://v1.hitokoto.cn')
      .then(response => response.json())
      .then(data => {
        const hitokoto = document.getElementById('hitokoto')
        hitokoto.innerText = data.hitokoto
      })
      .catch(console.error)
    </script>
    <!-- 如果你配置了 axios -->
    <script>
    axios.get('https://v1.hitokoto.cn')
      .then(({ data }) => {
        const hitokoto = document.getElementById('hitokoto')
        hitokoto.innerText = data.hitokoto
      })
      .catch(console.error)
    </script>
    <!-- 如果你的站点使用了 jQuery(如果是 JQ 3.x 以及更新的版本, 你得使用完整版的 JQ), 那么你可以... -->
    <script>
    $.ajax({
      type: 'GET',
      url: 'https://v1.hitokoto.cn',
      dataType: 'jsonp',
      jsonp: 'callback',
      jsonpCallback: 'hitokoto',
      success (data) {
        $('#hitokoto').text(data.hitokoto)
      },
      error (jqXHR, textStatus, errorThrown) {
        // 错误信息处理
        console.error(textStatus, errorThrown)
      }
    })
    </script>
    <!-- P.S 我们不推荐使用 jQuery Ajax。 推荐使用 fetch api 或者 axios.js-->
    <!-- 老式写法,兼容性最好; 支持 IE -->
    <script>
    var xhr = new XMLHttpRequest();
    xhr.open('get', 'https://v1.hitokoto.cn');
    xhr.onreadystatechange = function () {
      if (xhr.readyState === 4) {
        var data = JSON.parse(xhr.responseText);
        var hitokoto = document.getElementById('hitokoto');
        hitokoto.innerText = data.hitokoto;
      }
    }
    xhr.send();
    </script>
    <!-- 新 API 方法, 十分简洁 -->
    <script src="https://v1.hitokoto.cn/?encode=js&select=%23hitokoto" defer></script>

    插件:网易云的使用

    // 本示例需要浏览器支持 Promise,fetch 以及 ES6 语法。
    function fetch163Playlist(playlistId) {
    return new Promise((ok, err) => {
      fetch(`https://v1.hitokoto.cn/nm/playlist/${playlistId}`)
        .then(response => response.json())
        .then(data => {
          const arr = [];
          data.playlist.tracks.map(function (value) {
            arr.push(value.id);
          });
          return arr;
        })
        .then(fetch163Songs)
        .then(ok)
        .catch(err);
    });
    }
    function fetch163Songs(Ids) {
    return new Promise(function (ok, err) {
      let ids;
      switch (typeof Ids) {
        case 'number':
          ids = [Ids];
          break;
        case 'object':
          if (!Array.isArray(Ids)) {
            err(new Error('Please enter array or number'));
            return;
          }
          ids = Ids;
          break;
        default:
          err(new Error('Please enter array or number'));
          return;
          break;
      }  
      fetch(`https://v1.hitokoto.cn/nm/summary/${ids.join(',')}?lyric=true&common=true`)
        .then(response => response.json())
        .then(data => {
          var songs = [];
          data.songs.map(function (song) {
            songs.push({
              name: song.name,
              url: song.url,
              artist: song.artists.join('/'),
              album: song.album.name,
              pic: song.album.picture,
              lrc: song.lyric
            });
          });
          return songs;
        })
        .then(ok)
        .catch(err);
    });
    }
    // 使用测试
    fetch163Playlist(2158283120)
    .then(console.log)
    .catch(console.error);
    fetch163Songs([28391863, 22640061])
    .then(console.log)
    .catch(console.error);
😀
本文链接:
https://www.cqbg.ga/2020/05/04/%E5%85%B3%E4%BA%8E%E4%B8%80%E8%A8%80API%E7%9A%84%E4%BD%BF%E7%94%A8/