绕口令与谜语查询：5 分钟快速接入（从注册到第一条结果）
绕口令查询谜语查询API快速接入Python示例免费接口 # 绕口令与谜语查询：5 分钟快速接入（从注册到第一条结果）
**接口**：绕口令与谜语查询（apiCode=1623）· 接入点 1623-1 绕口令 / 1623-2 谜语｜**是否免费**：免费（含使用档次限制）｜**请求方式**：POST/GET｜**返回格式**：JSON｜**适用人群**：新注册用户、教师、小程序初学者｜**阅读时间**：约 5 分钟
## 核心要点
- 三个动作即可跑通：注册账号 → 在控制台拿到 AppKey → 用 AppKey 调用接口。
- 两个接入点共用同一套调用方式，仅路径与参数不同（绕口令用 `title`，谜语用 `question`）。
- 所有文章示例代码均「替换 AppKey 即可运行」，超时按接入点设置（绕口令 5s、谜语 15s）。
## Why：这跟我有什么关系？
绕口令是练口才、练普通话的利器；谜语能锻炼记忆力与反应力。无论你是想给自家孩子做识字卡片、给班级做口才打卡小程序，还是单纯想在公司群里发个「今日绕口令」互动，这个**免费**接口都能让你几行代码拿到现成内容，不用自己维护语料库。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口地址（绕口令） | `https://route.showapi.com/1623-1?appKey={your_appKey}` |
| 接口地址（谜语） | `https://route.showapi.com/1623-2?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 鉴权 | Query 参数 `appKey`（从 ShowAPI 控制台获取） |
| 计费 | 免费，但设有使用档次限制（防止滥用） |
| 超时（来自 OpenAPI） | 绕口令 5s；谜语 15s |
| 集成能力 | MCP 配置、OpenAPI(YAML/JSON) 文档 |
前置条件：一个 ShowAPI 账号 + 一个可用的 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)）。
## How：三步跑通
### 步骤 1 · 获取 AppKey
登录 ShowAPI 后，进入 [AppKey 管理控制台](https://www.showapi.com/console#/myApp)，复制任意一个已创建的 AppKey。下文用 `YOUR_APPKEY` 占位。
### 步骤 2 · 第一次调用（绕口令，关键词「扁担」）
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY"
# 绕口令接入点 1623-1；谜语用 1623-2
URL = "https://route.showapi.com/1623-1"
resp = requests.post(
URL,
params={"appKey": APP_KEY},
data={"title": "扁担", "page": "1"},
timeout=5, # 绕口令 5s；谜语请改为 15
)
data = resp.json()
body = data["showapi_res_body"]
if body["ret_code"] == "0":
for item in body["contentlist"]:
print(f"{item['title']}：{item['content']}")
else:
print("调用失败：", data.get("showapi_res_error"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1623-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "title=%E6%89%81%E6%8B%85&page=1"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const url = `https://route.showapi.com/1623-1?appKey=${APP_KEY}`;
const body = new URLSearchParams({ title: "扁担", page: "1" });
const resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body,
signal: AbortSignal.timeout(5000), // 绕口令 5s；谜语 15s
});
const data = await resp.json();
const resBody = data.showapi_res_body;
if (resBody.ret_code === "0") {
for (const item of resBody.contentlist) {
console.log(`${item.title}：${item.content}`);
}
} else {
console.error("调用失败：", data.showapi_res_error);
}
```
### 步骤 3 · 第一次调用（谜语，关键词「云南」）
只需把路径改成 `1623-2`、参数 `title` 改成 `question`、超时改成 `15s`：
```python
import requests
APP_KEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/1623-2",
params={"appKey": APP_KEY},
data={"question": "云南", "page": "1"},
timeout=15, # 谜语接入点超时为 15s
)
data = resp.json()
body = data["showapi_res_body"]
if body["ret_code"] == "0":
for item in body["contentlist"]:
print(f"谜面：{item['question']} 谜底：{item['answer']}")
```
## 返回示例与解析
```json
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "67aed69ffb638c23e1f1cfd9",
"showapi_res_body": {
"allPages": 100,
"ret_code": "0",
"contentlist": [
{
"content": "板凳宽，扁担长。扁担没有板凳宽，板凳没有扁担长。",
"title": "板凳与扁担"
}
],
"currentPage": 1,
"allNum": 10,
"maxResult": 1000
}
}
```
- `showapi_res_body.ret_code` 为 `"0"` 表示业务成功；非 0 见 `showapi_res_error`。
- `contentlist` 是数组，绕口令每项含 `title`+`content`，谜语每项含 `question`+`answer`。
- 分页四字段：`maxResult`（单页上限）、`allNum`（总数）、`allPages`（总页数）、`currentPage`（当前页）。详见[返回字段全解](https://www.showapi.com/guides/tongue-riddle-response-fields-1623)。
## 进阶 / 边界
- 关键词留空（`title=` 或 `question=` 不传）会返回该内容库的默认列表，可用来做「随机一条」。
- 免费接口有档次限制，循环调用前请看[免费档位下的调用纪律与本地缓存策略](https://www.showapi.com/guides/tongue-riddle-cache-tier-1623)。
- 想直接扔进 AI 客户端用？见[MCP 集成](https://www.showapi.com/guides/tongue-riddle-mcp-integration-1623)。
## FAQ
**Q1：提示没有权限 / 失败，可能是什么原因？**
A：先确认 AppKey 正确且接口已开通；非 0 的 `ret_code` 配合 `showapi_res_error` 看具体信息，详见[错误处理](https://www.showapi.com/guides/tongue-riddle-error-handling-1623)。
**Q2：免费接口会不会突然收费？**
A：文档标注为免费服务，但有使用档次限制（防滥用）。具体档位以[官方档位说明](https://www.showapi.com/free-api)为准，本文不编具体数字。
**Q3：GET 和 POST 用哪个？**
A：都支持。表单参数用 `application/x-www-form-urlencoded`；GET 时参数拼在 URL 上。
**Q4：超时设多少合适？**
A：绕口令接入点官方超时 5s，谜语 15s，建议客户端超时与之对齐或略大。
**Q5：一次能返回多少条？**
A：单页上限 `maxResult` 为 1000，默认页返回 10 条左右；翻页用 `page` 参数。
## 下一步阅读
- [绕口令与谜语查询：返回字段与 ret_code 全解](https://www.showapi.com/guides/tongue-riddle-response-fields-1623)
- [绕口令与谜语查询：绕口令关键词检索实战](https://www.showapi.com/guides/tongue-riddle-twister-query-1623)
- [绕口令与谜语查询：通过 MCP 在 Cherry Studio/ChatBox 中直接调用](https://www.showapi.com/guides/tongue-riddle-mcp-integration-1623)
- **本系列共 12 篇**：查看[绕口令与谜语查询指南总目录](https://www.showapi.com/guides/tongue-riddle-guides-1623)
