RandNext API

为 48 个 RandNext 工具提供免费的只读 JSON 接口。无需 API 密钥，即可生成数字、颜色、日期、骰子结果、精选内容等。版本 1 的基础路径为 /api/v1。

快速开始

curl https://randnext.com/api/v1/jokes/random

curl "https://randnext.com/api/v1/tools/random-number?min=1&max=100&count=5&unique=true"

const res = await fetch("https://randnext.com/api/v1/quotes/random?category=wisdom");
const quote = await res.json();
console.log(`“${quote.text}” — ${quote.author}`);

接口

精选内容保留列表、随机和按 ID 查询接口；生成器工具则统一使用基于工具 slug 的接口。

请求	返回内容
`GET /api/v1/{type}/random`	一个随机项目
`GET /api/v1/{type}?limit=1..20`	`{ data: Item[], count }` — 互不重复的随机项目（默认 10 个）
`GET /api/v1/{type}/{id}`	按 ID 返回一个项目（可缓存）
`GET /api/v1/tools/{slug}`	从 44 个受支持的实用工具中生成结果
`GET /api/v1/draws/{id}`	一个抽奖选择器抽奖记录：包含承诺值、参赛名单哈希，以及抽奖时间到达后的公开种子和获奖者。读取已到期的抽奖会触发揭晓。
`GET /api/v1/draws/{id}/entries`	以 text/plain 原样返回锁定的参赛名单；其 SHA-256 为 entries_hash。隐藏名单需要组织者的管理令牌。
`POST /api/v1/draws/{id}/cancel`	仅限组织者：在抽奖时间前取消抽奖。记录仍会以已取消状态公开保留。
`PATCH /api/v1/draws/{id}`	仅限组织者：将 listed 设为 true 或 false，或将 purge_entries 设为 true，以在抽奖后删除已存储名单。
`GET /api/v1/health`	服务状态
`GET /api/v1/openapi.json`	OpenAPI 3.1 描述文件

抽奖组织者操作需发送 Authorization: Bearer <管理令牌>，且仅接受来自 randnext.com 或服务端代码的请求，不接受其他网站发起的请求。可使用randnext-draw-v1 规范重新计算并核验任意抽奖。

查询参数

category — 笑话：general, programming, dad, pun, animal；名言：inspirational, life, work, humor, wisdom；问题：icebreaker, classroom, friends, deep, would-you-rather；单词：noun, verb, adjective, adverb。
safety — family（仅家庭级内容）或 general（默认：家庭级和普通级）。接口永不返回成人内容。
仅单词接口： min_length, max_length （1–30），以及 starts_with（一个字母）。
生成器参数取决于具体工具。常用选项包括 count, min, max, group, unique, sort. 每个工具页面都提供可直接运行的请求。
未知参数或超出工具允许范围的值会返回 400 INVALID_PARAMETER。

响应

实用生成器返回统一的响应结构：

{
  "tool": "random-number",
  "data": [
    { "value": "18" },
    { "value": "72" }
  ],
  "count": 2,
  "permalink": "https://randnext.com/random-number"
}

精选内容接口还会返回更完整的来源和许可字段：

{
  "id": "qt_000001",
  "type": "quote",
  "text": "Well done is better than well said.",
  "author": "Benjamin Franklin",
  "category": "wisdom",
  "tags": [],
  "language": "en",
  "safety_level": "family",
  "source_url": null,
  "license": "public-domain",
  "attribution": "Poor Richard’s Almanack (1737)",
  "permalink": "https://randnext.com/random-quote?id=qt_000001"
}

当 attribution 不为 null 时，必须在内容旁显示该字段。

错误

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please try again later." } }

400	INVALID_PARAMETER	参数无效，例如分类未知或 limit 超出范围。
401	UNAUTHORIZED	仅限抽奖组织者操作：管理令牌缺失或错误。
404	NOT_FOUND	类型或 ID 未知、项目已移除，或没有内容符合筛选条件。
409	CONFLICT	仅限抽奖组织者操作：抽奖当前状态不允许执行该操作。
429	RATE_LIMITED	请求过多，请等待 Retry-After 指定的秒数。
500	INTERNAL_ERROR	服务端发生错误。
503	SERVICE_UNAVAILABLE	服务暂时不可用或正在维护。

限制与缓存

每个 IP 每分钟 60 次、每天 1,000 次请求。每个响应都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。
随机接口不会缓存；按 ID 查询的响应和已结束的抽奖记录最多可缓存一小时。
允许任意来源发起 GET 请求。

使用条款

免费使用时，必须提供一个清晰可见的“Powered by RandNext”链接，指向 randnext.com。
只要响应中存在 attribution 字段，就必须显示它。
请勿下载整个内容库后重新发布或转售。
本服务不提供 SLA。我们可能调整限制或屏蔽滥用流量。

支持

公开 API 目前覆盖 48 个工具。密码、PIN 和秘密令牌等安全敏感生成器仅在浏览器中运行，生成的秘密不会到达服务器。如有 API 问题或需要报告故障，请发送邮件至 support@randnext.com，并附上接口地址和响应状态。

RandNext API

快速开始

接口

查询参数

支持的工具

响应

错误

限制与缓存

使用条款

支持