随机一言

接口说明

随机一言接口用于随机返回一条一言语句，适合在页面展示、内容点缀或轻量文案填充等场景调用。无需密钥，免费使用，以 GET 方式请求即可获得结果。

调用地址

https://mini10.top/api/hitokoto.php

请求方式

使用 HTTP GET 方法发起请求。该接口不含任何请求参数，直接访问上述调用地址即可获得返回内容。

鉴权说明

本接口无需密钥，也无需在请求中携带任何身份凭证，直接调用即可。该接口免费提供，不产生计费。

请求参数

本接口不接收任何请求参数。使用 GET 方式请求调用地址即可获得一条随机一言内容。

取值说明

• 调用地址：https://mini10.top/api/hitokoto.php
• 请求方式：GET
• 请求体中无需携带任何字段，也不需要附加查询字符串。

成功响应示例

请求成功后返回 JSON 对象，业务数据位于 data 字段中：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1024,
    "uuid": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "hitokoto": "愿你走出半生，归来仍是少年。",
    "type": "d",
    "from": "随机一言",
    "from_who": null,
    "creator": "hitokoto",
    "created_at": "2024-05-18 09:30:12"
  }
}

每次调用返回一条随机语句，具体内容与来源随抽取结果变化。

响应字段说明

说明：data 中各字段均为只读返回值，调用方无需提交任何参数即可获取。若某条语句缺少出处或作者信息，对应字段可能返回 null 或空字符串，请在使用前做空值判断。

错误响应示例

接口在发生业务异常时返回 JSON，code 固定为 0，具体原因由 msg 与 errcode 表示：

{"code":0,"msg":"接口维护中","errcode":11006}

{"code":0,"msg":"请求过于频繁","errcode":11005}

业务错误码说明

本接口免费且无需密钥，密钥类与积分类错误码通常不会在正常调用中触发；实际常见错误为请求频率限制、接口维护或服务暂不可用。

调用示例

终端 curl（bash）

curl "https://mini10.top/api/hitokoto.php"

PHP

// PHP
$url = 'https://mini10.top/api/hitokoto.php';
$response = file_get_contents($url);

if ($response === false) {
    echo '请求失败';
} else {
    echo $response;
}

注意事项

• 无需鉴权：本接口不要求任何密钥，调用时不需要在 Query 或 Header 中附加身份凭证，JSON 请求参数为空；因此无需考虑密钥保管问题，也请勿在请求里重复传入任何鉴权字段。
• 请求地址固定：调用地址为 https://mini10.top/api/hitokoto.php，请完整使用该路径，不要增删路径层级、不要改写域名，端点变更时以下发的实际地址为准。
• 不要添加多余参数：本接口没有定义任何请求参数，自行拼接的查询参数（如自定义格式、分类、编码等）不在支持范围内，可能被忽略或导致返回结果不符合预期，请保持请求为无参 GET。
• 建议使用 HTTPS：调用地址已为 HTTPS，请勿降级为 HTTP，以免返回内容在传输链路中被篡改或截断。
• 内容随机且不可控：返回的句子为随机抽取，每次结果不同，可能出现重复、空内容、超长文本或语义不合适的句子。请勿把返回内容当作事实性信息或权威来源直接展示给终端用户，建议在客户端做长度截断、空白校验与敏感词过滤。
• 做好空值与异常处理：未提供返回示例，代表返回结构可能随时调整。请按「可能为空、可能格式变化」来编写容错逻辑，不要硬编码固定字段或固定长度；请求失败时应降级为本地备用文案，而不是让页面报错或留白。
• 控制调用频率：接口免费开放，请勿以轮询、并发压测或爬取目的高频调用。同一页面建议每次访问只取一条，并对结果做短期缓存（例如前端会话内复用同一句子），避免刷新即请求。
• 注意字符编码：返回内容可能包含多语言与特殊符号，请按 UTF-8 解析，避免在非 UTF-8 页面上直接输出导致乱码。
• 合理设置超时与重试：建议设置较短超时并在失败时最多重试一次，重试仍失败则使用本地兜底内容，防止第三方不可用拖慢自身页面加载。
• 避免在前端以外滥用：本接口虽无密钥，但请勿将其包装为自有数据源批量分发或用于商业转售；如需大量文本素材，建议自行本地化存储。