小程序每日一谜怎么做：riddle 接口接入示例

做小程序互动、儿童内容页、节日活动、答题小游戏时，谜语是一类很好用的轻量内容。它不需要复杂的素材制作，又天然适合"先展示题目，再揭晓答案"的交互。

riddle 接口就是一个谜语内容 API。它支持三种模式：随机返回一条谜语、分页获取谜语列表、获取谜语类型列表。也就是说，你既可以用它做"随机猜谜"按钮，也可以用它做分类浏览和题库列表。

这个接口适合做什么

riddle 的定位是谜语大全接口，核心能力是按不同 action 返回谜语内容或分类信息。

它比较适合这些场景：

• 小程序里的每日一谜、随机猜谜功能
• H5 活动页里的互动答题模块
• 儿童内容产品里的益智题库
• 博客、工具站、公众号素材页里的趣味内容卡片
• 后台内容系统里的谜语分类和分页管理

我觉得它最实用的一点是：不是只能随机拿一条，而是把 random、list、types 三种模式放在同一个接口里。前期做 demo 可以先用随机模式，后面要做题库页，再接列表和分类。

基本接入信息

接口地址：

POST https://v1.apizero.cn/api/riddle

请求头：

Header	必填	说明
X-Api-Key	否	携带 API Key 可获得更高调用频度和更快速率
Content-Type	建议	POST JSON 请求建议使用 application/json

请求参数：

参数	类型	必填	说明
action	string	否	random、list、types，默认 random
type	string	否	list 模式下使用，表示谜语类型，小写字母
page	string	否	list 模式下使用，页码，默认 1

三个常见请求分别是：

{"action": "random"}

{"action": "types"}

{"action": "list", "type": "ertongmiyu", "page": "1"}

cURL 调用示例

随机获取一条谜语：

curl -X POST "https://v1.apizero.cn/api/riddle" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "random"
  }'

获取类型列表：

curl -X POST "https://v1.apizero.cn/api/riddle" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "types"
  }'

分页查询儿童谜语：

curl -X POST "https://v1.apizero.cn/api/riddle" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "list",
    "type": "ertongmiyu",
    "page": "1"
  }'

如果已经申请了 API Key，可以加上：

-H "X-Api-Key: YOUR_API_KEY"

2026-05-30 实测：random 模式

随机模式返回的是单条谜语。我实测传入：

{"action": "random"}

返回示例：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "title": "刮净胡子，鼻直口方，一表人才--打一诗词句",
    "content": "刮净胡子，鼻直口方，一表人才",
    "answer": "须尽丘壑美",
    "type": ""
  },
  "request_id": "mprx0nywd6f5cbfd"
}

单条谜语的核心字段很好理解：

字段	类型	说明
title	string	谜语标题，可能包含"打一字""打一诗词句"等提示
content	string	谜面正文
answer	string	谜底
type	string	谜语类型，部分返回可能为空

做页面时，建议先展示 title 或 content，答案放到按钮点击后再显示，这样才有猜谜的互动感。

2026-05-30 实测：types 模式

类型列表模式用于获取可用分类。我实测传入：

{"action": "types"}

返回里有 types 数组和 count：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "types": [
      {
        "type": "chengyumiyu",
        "name": "成语谜语",
        "desc": "顾名思义，成语谜指猜成语的谜语。"
      },
      {
        "type": "ertongmiyu",
        "name": "儿童谜语",
        "desc": "儿童谜语是指适合儿童青少年的谜语..."
      }
    ],
    "count": 12
  },
  "request_id": "mprx0nzledf1ab91"
}

实测里一共返回 12 个类型，例如：

type	name
chengyumiyu	成语谜语
zhiliwenda	智力问答
shiwumiyu	事物谜语
shiwenmiyu	诗文谜语
naojinjizhuanwan	脑筋急转弯
ertongmiyu	儿童谜语
zimi	字谜

类型列表适合用来初始化筛选菜单。比如页面打开时先请求 types，用户选中"儿童谜语"后，再用 list + type=ertongmiyu 查询具体内容。

2026-05-30 实测：list 模式

列表模式返回分页谜语数组。我实测传入：

{
  "action": "list",
  "type": "ertongmiyu",
  "page": "1"
}

返回结构如下：

{
  "code": 0,
  "msg": "成功",
  "data": {
    "type": "ertongmiyu",
    "page": 1,
    "count": 10,
    "items": [
      {
        "title": "脸上长钩子，头角挂扇子，四根粗柱子，一条小辫子。（猜一动物）",
        "content": "脸上长钩子，头角挂扇子，四根粗柱子，一条小辫子。（猜一动物）",
        "answer": "象",
        "type": ""
      }
    ]
  },
  "request_id": "mprx12pcc9c04e12"
}

列表模式重点看这几个字段：

字段	类型	说明
data.type	string	当前查询类型，未指定时可能为 all
data.page	number	当前页码
data.count	number	当前返回条数，实测每页 10 条
data.items	array	谜语数组，每项包含 title、content、answer、type

Python 调用示例

下面这个封装同时支持随机、类型列表和分页查询：

import requests


def query_riddle(
    action: str = "random",
    riddle_type: str | None = None,
    page: int | None = None,
    api_key: str | None = None,
) -> dict:
    payload = {
        "action": action,
    }

    if riddle_type:
        payload["type"] = riddle_type
    if page:
        payload["page"] = str(page)

    headers = {
        "Content-Type": "application/json",
    }
    if api_key:
        headers["X-Api-Key"] = api_key

    resp = requests.post(
        "https://v1.apizero.cn/api/riddle",
        headers=headers,
        json=payload,
        timeout=15,
    )
    resp.raise_for_status()
    result = resp.json()

    if result.get("code") != 0:
        raise RuntimeError(result.get("msg") or result.get("message") or "请求失败")

    return result["data"]


random_item = query_riddle("random")
print("谜面:", random_item["content"])
print("谜底:", random_item["answer"])

types = query_riddle("types")
print("类型数量:", types["count"])

children = query_riddle("list", riddle_type="ertongmiyu", page=1)
print("儿童谜语条数:", children["count"])

JavaScript 调用示例

Node.js 18+ 可以直接用 fetch：

async function queryRiddle({ action = "random", type, page, apiKey } = {}) {
  const payload = { action };

  if (type) payload.type = type;
  if (page) payload.page = String(page);

  const headers = {
    "Content-Type": "application/json",
  };

  if (apiKey) {
    headers["X-Api-Key"] = apiKey;
  }

  const res = await fetch("https://v1.apizero.cn/api/riddle", {
    method: "POST",
    headers,
    body: JSON.stringify(payload),
  });

  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }

  const data = await res.json();
  if (data.code !== 0) {
    throw new Error(data.msg || data.message || "请求失败");
  }

  return data.data;
}

const item = await queryRiddle({ action: "random" });
console.log(item.content, item.answer);

const typeList = await queryRiddle({ action: "types" });
console.table(typeList.types);

const pageData = await queryRiddle({
  action: "list",
  type: "ertongmiyu",
  page: 1,
});
console.table(pageData.items);

如果做成前端答题卡片，可以把答案先隐藏：

const card = {
  question: item.content,
  answer: item.answer,
  revealed: false,
};

用户点击"查看答案"时再把 revealed 改成 true。

接到业务里的几个小建议

第一，做请求节流。实测时如果短时间内连续请求，接口会返回类似下面的结果：

{
  "code": 4029,
  "msg": "调用过快，请稍后再试",
  "data": {
    "limit_qps": 2,
    "retry_after": 1
  }
}

所以页面按钮最好加 loading 状态，后端也可以做短时间缓存，避免用户连续点击触发过快调用。

第二，page 虽然是页码，但文档里类型写的是 string。实际传数字字符串最稳，比如 "1"、"2"。

第三，type 字段建议来自 types 接口，不要在前端硬编码。这样后续分类有变化时，页面能跟着接口返回走。

第四，谜语答案适合延迟展示。无论是随机模式还是列表模式，都不要一上来把 answer 放在最显眼的位置，否则互动效果会弱很多。