猜一猜谜语 API：5 分钟接入，调通你的第一条随机谜语
猜一猜谜语APIAPI快速接入Python示例免费接口 # 猜一猜谜语 API：5 分钟接入，调通你的第一条随机谜语
> 接口/接入点：猜一猜谜语 API · 随机查询谜语（151-2） · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 注册并拿到 AppKey 后，向 `https://route.showapi.com/151-2?appKey=YOUR_APPKEY` 发一个表单请求即可拿到 20 条随机谜语。
- 接入点 151-2 只有一个可选参数 `typeId`（按类型筛选），不传则返回全类型随机谜语。
- 返回结构存在文档内部矛盾（详见进阶/边界），解析代码务必做防御性处理，推荐优先读 [返回字段全解](https://www.showapi.com/guides/riddle-response-fields-151)。
## Why：这跟我有什么关系
想在 App、小程序、公众号、社群机器人里加一个"每日一谜""趣味答题"模块？猜一猜谜语 API 是**免费**的，注册即用，覆盖搞笑、字谜、成语、脑筋急转弯、智力问答等 26 类主题，省去你自己收集、清洗题库。本文帮你 5 分钟内发出第一次成功调用。
## What：前置条件与接口速览
| 项 | 内容 |
|----|------|
| 接口地址 | `https://route.showapi.com/151-2?appKey=YOUR_APPKEY` |
| 接入点 | 151-2 随机查询谜语 |
| 请求方式 | POST / GET |
| 鉴权 | query 参数 `appKey`（ShowAPI 控制台获取） |
| 计费 | 免费（防滥用设档位限制，以官方 /free-api 为准） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档（见 [MCP 接入](https://www.showapi.com/guides/riddle-mcp-151) / [OpenAPI 导入](https://www.showapi.com/guides/riddle-openapi-151)） |
前置条件：已注册 ShowAPI 账号并拥有 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)）。
## How：三步调通
### 步骤 1 — 获取 AppKey
登录 ShowAPI 控制台 → 我的应用 → 复制 AppKey，替换下面代码中的 `YOUR_APPKEY`。
### 步骤 2 — 发起请求（三语言任选）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/151-2"
params = {"appKey": "YOUR_APPKEY"}
data = {"typeId": "gxmy"} # 可选：搞笑谜语；不传则返回全类型随机
try:
resp = requests.post(url, params=params, data=data, timeout=10)
resp.raise_for_status()
body = resp.json()
if body.get("showapi_res_code") != 0:
print("系统级错误:", body.get("showapi_res_error"))
else:
rb = body["showapi_res_body"]
# 注意：文档返回示例为 pagebean.contentlist（数组）；OpenAPI schema 描述为单条扁平结构。
# 防御性解析：优先取数组，兼容扁平形态。
items = None
if "pagebean" in rb and "contentlist" in rb.get("pagebean", {}):
items = rb["pagebean"]["contentlist"]
elif "contentlist" in rb:
items = rb["contentlist"]
elif "Title" in rb:
items = [rb]
for it in (items or []):
print("谜面:", it.get("Title") or it.get("title"))
print("谜底:", it.get("Answer") or it.get("answer"))
print("类型:", it.get("typeName"), "\n")
except requests.RequestException as e:
print("请求失败:", e)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/151-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "typeId=gxmy"
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/151-2?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ typeId: "gxmy" });
fetch(url, { method: "POST", body, timeout: 10000 })
.then(r => r.json())
.then(json => {
const rb = json.showapi_res_body;
const pb = rb.pagebean || rb;
const list = pb.contentlist || (rb.Title ? [rb] : []);
list.forEach(it => {
console.log("谜面:", it.Title || it.title);
console.log("谜底:", it.Answer || it.answer);
});
})
.catch(e => console.error("请求失败:", e));
```
### 步骤 3 — 解析返回
业务数据在 `showapi_res_body`。先用 `showapi_res_code` 判断系统级成败，再用 `ret_code`（在 `showapi_res_body` 内，`0` 为成功）判断业务成败，最后读取谜面/谜底。
## 返回示例与解析
文档返回示例（节选）结构如下，每条含 `Title`（谜面）、`Answer`（谜底）、`typeId`、`typeName`：
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"pagebean": {
"allNum": 20,
"allPages": 1,
"contentlist": [
{ "Title": "问：有一头头朝北的牛…", "Answer": "答：朝地", "typeId": "zlmy", "typeName": "智力问答" }
],
"currentPage": 1,
"maxResult": 20
},
"ret_code": 0
}
}
```
字段表见 [返回字段全解](https://www.showapi.com/guides/riddle-response-fields-151)。
## 进阶/边界
- **返回结构文档矛盾（重要）**：151-2 的"返回示例"是 `pagebean.contentlist`（20 条数组），但"返回体字段表"与 OpenAPI schema 却描述为单条扁平结构（`Title`/`Answer` 直接挂在 `showapi_res_body` 下，无 `pagebean`）。请以实际返回为准，代码做防御性解析（上文已示范）。完整对照见 [字段大小写避坑](https://www.showapi.com/guides/riddle-field-case-151)。
- 接入点 151-2 的 `Title`/`Answer` 为**首字母大写**；而 151-4 接入点是小写 `title`/`answer`，解析时别混用。
- 免费接口设档位限制，批量/高频调用前先看 [免费频控与缓存建议](https://www.showapi.com/guides/riddle-rate-limit-151)。
## FAQ
**Q1：返回 0 条或报错怎么办？**
先检查 `showapi_res_code` 与 `showapi_res_error`（系统级），再看 `showapi_res_body.ret_code`。免费接口若超出档位限制会被限流，确认 AppKey 有效且未超频。
**Q2：typeId 填什么值？**
26 类完整对照见 [类型清单](https://www.showapi.com/guides/riddle-typelist-151)。不传 `typeId` 则返回全类型随机谜语。
**Q3：接口收费吗？**
免费。注册后默认可调用，为防止滥用设档位限制，具体额度以官方 /free-api 为准，本文不编造数字。
**Q4：能按关键词搜谜语吗？**
随机查询（151-2）只支持按 `typeId` 类型筛选。按类型分页查询（151-4）同样**无关键词参数**，详见 [151-4 实战](https://www.showapi.com/guides/riddle-search-by-type-151)。
## 相关能力 / 下一步阅读
- [猜一猜谜语 API 返回字段全解：三大接入点的 Title/Answer 与分页差异](https://www.showapi.com/guides/riddle-response-fields-151)
- [猜一猜谜语 API 类型清单：26 类谜语 typeId 完整对照表](https://www.showapi.com/guides/riddle-typelist-151)
- [用 MCP 在 AI 客户端里直接玩猜谜：Cherry Studio / ChatBox 接入 151](https://www.showapi.com/guides/riddle-mcp-151)
- **本系列共 13 篇**：查看[猜一猜谜语 API 指南总目录](https://www.showapi.com/guides/riddle-guides-151)
