OneHitokoto-API#

支持多平台部署的一言API服务，使用 hitokoto-osc/sentences-bundle 作为句子源。

功能特性#

随机获取一言，支持按分类筛选
支持多种返回格式：encode=json（默认）、text、js；callback 参数触发 JSONP
支持按句子长度过滤
提供分类列表接口（GET /api/categories.json）
全 CORS 支持，跨域友好
边缘缓存加速 + 内存预加载
构建期多源镜像切换，运行时读同站数据 + 缓存 + 内联备用
支持多平台部署：EdgeOne Pages、阿里云 ESA（对外接口一致，分支已分化，以 main 为准）

在线演示#

API 接口: https://hitokoto.api.sylv.top/api

API 文档#

获取随机一言#

1
GET /api

请求参数#

参数	类型	必填	说明
c / category	string	否	句子分类，如 `a`(动画), `b`(漫画), `c`(游戏) 等；非法取值静默回退为随机
encode / format	string	否	返回格式：`json`(默认), `text`, `js`；`callback` 存在时按 JSONP 包裹
callback	string	否	JSONP 回调函数名（仅与 `encode=json` 组合有效）
min_length	number	否	最小句子长度（包含）
max_length	number	否	最大句子长度（包含，默认不限）

句子分类#

分类码	名称	说明
a	动画	Anime
b	漫画	Comic
c	游戏	Game
d	文学	Literature
e	原创	Original
f	网络	Internet
g	其他	Other
h	影视	Movie
i	诗词	Poetry
j	网易云	Netease
k	哲学	Philosophy
l	抖机灵	Wit

响应示例 (JSON)#

1
{
2
  "id": 7338,
3
  "uuid": "75a45fd4-4f2f-45eb-80cb-6f0a7bcdfaf2",
4
  "hitokoto": "用代码表达言语的魅力，用代码书写山河的壮丽。",
5
  "type": "f",
6
  "from": "一言开发者中心",
7
  "from_who": "一言",
8
  "creator": "DreamOne",
9
  "creator_uid": 9209,
10
  "length": 22,
11
  "category_name": "网络",
12
  "category_desc": "Internet"
13
}

示例请求#

1
# 获取随机一言（JSON格式）
2
curl https://hitokoto.api.sylv.top/api
3

4
# 获取动画类一言
5
curl https://hitokoto.api.sylv.top/api?c=a
6

7
# 获取纯文本格式
8
curl https://hitokoto.api.sylv.top/api?encode=text
9

10
# JSONP 回调
11
curl https://hitokoto.api.sylv.top/api?callback=myCallback
12

13
# 长度过滤
14
curl "https://hitokoto.api.sylv.top/api?min_length=10&max_length=50"

获取分类列表#

1
GET /api/categories.json

响应示例#

1
{
2
  "code": 200,
3
  "data": [
4
    { "key": "a", "name": "动画", "desc": "Anime" },
5
    { "key": "b", "name": "漫画", "desc": "Comic" },
6
    ...
7
  ],
8
  "count": 12
9
}

部署方式#

本项目支持两种平台部署，请根据需求选择：

平台一：EdgeOne Pages（腾讯云）#

基于 EdgeOne Pages Edge Functions 部署，全球边缘节点，超低延迟。

1. 通过 EdgeOne CLI 部署#

1
# 安装 CLI
2
npm install -g @edgeone/cli
3

4
# 登录
5
edgeone login
6

7
# 部署
8
edgeone deploy

2. 通过 Git 导入部署#

Fork 本仓库
登录 EdgeOne Pages 控制台
选择「导入 Git 仓库」，授权并选择本仓库
点击部署，等待构建完成

3. 通过 Pages MCP 部署#

使用支持 MCP 的编辑器（如 Cursor、Trae），配置 Pages MCP Server 后直接部署。

平台二：阿里云 ESA（`aliyun-esa` 分支）#

基于阿里云 ESA（Edge Security Acceleration）函数和 Pages 部署。以下配置与构建脚本只属于该分支：

1. 环境准备#

注册并登录阿里云 ESA 控制台
确保已开通 ESA 服务并创建站点

2. 配置部署#

项目已包含 esa.jsonc 配置文件：

1
{
2
  "name": "hitokoto-api",
3
  "entry": "./build/api.js",
4
  "installCommand": "",
5
  "buildCommand": "node scripts/build.js",
6
  "assets": {
7
    "directory": "./dist",
8
    "notFoundStrategy": "404Page"
9
  }
10
}

3. 构建与部署#

1
# 安装依赖
2
npm install
3

4
# 构建项目（打包函数 + 静态资源）
5
npm run build
6

7
# 使用 ESA CLI 或控制台上传部署

构建脚本会将句子数据内联到函数中，生成 build/api.js，同时将静态资源输出到 dist/ 目录。

注意：函数包大小限制为 4MB，构建时会自动检查。

数据更新#

句子数据存储在 data/ 目录下，可通过以下方式更新：

1
# 手动更新
2
node scripts/fetch-sentences.js
3

4
# 或使用 PowerShell 脚本（Windows）
5
.\scripts\update-sentences.ps1
6

7
# 或使用 Bash 脚本（Linux/macOS）
8
./scripts/update-sentences.sh

项目已配置 GitHub Actions 自动更新工作流（.github/workflows/update-sentences.yml），每天凌晨 3 点 (UTC) 自动从远程源获取最新数据。

技术栈#

EdgeOne Pages - 腾讯云边缘计算平台
阿里云 ESA - 阿里云边缘安全加速
Edge Functions - 边缘函数
hitokoto-osc/sentences-bundle - 句子数据源

项目结构#

1
.
2
├── api/
3
│   └── categories.json              # 分类列表静态数据
4
├── data/                            # 句子 JSON 数据（main，2026-09-12 实测共 11039 条）
5
│   ├── a.json ~ l.json              # 各分类句子数据
6
│   └── index.json                   # 数据索引（统计信息）
7
├── edge-functions/
8
│   └── api.js                       # 一言API核心接口 (/api，main 实测 484 行)
9
├── scripts/
10
│   ├── fetch-sentences.js           # 获取句子数据（多源镜像，构建期有效）
11
│   ├── update-sentences.ps1         # PowerShell 更新脚本
12
│   └── update-sentences.sh          # Bash 更新脚本
13
├── .github/workflows/
14
│   └── update-sentences.yml         # 自动更新工作流（每天 03:00 UTC）
15
├── edgeone.json                     # EdgeOne Pages 配置（静态数据 86400s，API 响应 s-maxage=60）
16
├── index.html                       # 首页（API文档 + 演示）
17
├── package.json
18
└── README.md

esa.jsonc、scripts/build.js、build/api.js、dist/ 与 4 MB 函数包限制只属于 aliyun-esa 分支，不在 main 中。该分支落后 main 约 112 个提交，数据停留在 2026-05-29，对外接口一致，但以 main 为准。

分支说明#

main：主分支，默认针对 EdgeOne Pages 优化
aliyun-esa：阿里云 ESA 适配分支，包含 ESA 专属配置和构建脚本

对外接口一致，分支实现已分化（打包路线与数据新旧不同），以 main 为准。

参考文档#

开源协议#

MIT License