拾句

HTTP API

接口文档

读取随机语句和当前分类。示例基址：https://sent.andan.me

快速调用

每个示例都可直接复制运行，并会检查 HTTP 状态和处理错误信息。

随机一条

(async () => {
  try {
    const response = await fetch('https://sent.andan.me/api/v1');
    const body = await response.json();
    if (!response.ok) {
      throw new Error(`${body.code}: ${body.detail}`);
    }
    console.log(body.data);
  } catch (error) {
    console.error('读取失败', error);
  }
})();

按分类随机

(async () => {
  try {
    const response = await fetch('https://sent.andan.me/api/v1?categories=a');
    const body = await response.json();
    if (!response.ok) {
      throw new Error(`${body.code}: ${body.detail}`);
    }
    console.log(body.data);
  } catch (error) {
    console.error('读取失败', error);
  }
})();

限制长度

(async () => {
  try {
    const response = await fetch('https://sent.andan.me/api/v1?categories=a&min_length=10&max_length=1000');
    const body = await response.json();
    if (!response.ok) {
      throw new Error(`${body.code}: ${body.detail}`);
    }
    console.log(body.data);
  } catch (error) {
    console.error('读取失败', error);
  }
})();

GET /api/v1

从符合条件的已发布语句中等概率随机返回一条。每次请求独立抽取，因此可能连续返回同一句。

参数类型默认值限制
categories逗号分隔字符串全部启用分类去重后最多 20 个；请使用本页分类代码
min_length十进制整数0闭区间 0–1000
max_length十进制整数30闭区间 0–1000，且必须 ≥ min_length

分类：多个代码直接以英文逗号分隔，不加空格；重复代码会先去重。代码区分大小写。

长度：按 Unicode 码点计算。只传 min_length 时，max_length 仍为 30。

参数：未知参数、未知分类代码、同名参数重复、空值或非法编码返回 400。原始查询字符串最多 4096 字节。

结果：没有符合全部条件的语句时返回 404，不会放宽条件或改用其他分类。

返回字段

以下值仅为格式示意

{
  "data": {
    "uuid": "75a45fd4-4f2f-45eb-80cb-6f0a7bcdfaf2",
    "content": "今天也要认真写代码。",
    "category": "original",
    "source": "示例来源",
    "author": "",
    "length": 10
  },
  "meta": {"dataset_version": "1289"}
}
字段类型说明
data.uuid字符串语句的稳定标识
data.content字符串语句正文
data.category字符串分类代码
data.source字符串来源，未填写时为空字符串
data.author字符串作者，未填写时为空字符串
data.length整数正文的 Unicode 码点数
meta.dataset_version字符串本次响应使用的数据集版本

GET /api/v1/categories

不接受查询参数。返回所有启用分类，包括语句数为 0 的分类；先按后台排序值、再按分类代码排列。

响应中每项包含字符串 code、字符串 name 和整数 count；meta.dataset_version 与随机接口相同。

以下为响应格式示意：

{
  "data": [
    {"code": "original", "name": "原创", "count": 120}
  ],
  "meta": {"dataset_version": "1289"}
}

当前启用分类

代码名称语句数
a动画1465
b漫画110
c游戏1165
d文学1944
e原创1472
f网络1541
g其他1866
h影视196
i诗词753
j网易云139
k哲学307
l抖机灵81

错误响应

错误使用 application/problem+json。以下内容仅为格式示意：

{
  "type": "about:blank",
  "title": "参数无效",
  "status": 400,
  "detail": "包含未知查询参数",
  "request_id": "4dc0f8e4-2f41-4c61-b75f-46daaf28da9f",
  "code": "invalid-parameter"
}

根据 status 和 code 判断错误；detail 可用于提示，request_id 可在反馈问题时用于排查。

状态代码含义
400invalid-parameter参数、查询编码或请求体不符合要求
403cors-denied跨域预检不被允许
404not-found没有匹配结果或路径不存在
405method-not-allowed请求方法不受支持
503not-ready服务尚无可用数据

通用约定

  • 所有服务可控响应包含 X-Request-ID；业务接口返回 Cache-Control: no-store。
  • GET 成功响应使用 application/json。读取路由允许 GET、HEAD、OPTIONS；GET 和 HEAD 不接受请求体。
  • HEAD 执行相同校验但不返回响应体；普通 OPTIONS 返回 204 和 Allow。
  • 公开 API 可直接跨域请求，无需凭据。设置 CORS_ALLOWED_ORIGINS 后可限制来源；预检仅接受 GET、HEAD 及请求头 Accept、Content-Type。