周公解梦 API：5 分钟接入，从注册到查出第一个梦境解读
周公解梦快速接入Python示例免费接口关键词查询 # 周公解梦 API：5 分钟接入，从注册到查出第一个梦境解读
> 接口：免费解梦详细（apiCode 1601）· 接入点：解梦详细（1601-2）· **免费** · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读约 6 分钟
## 核心要点
- 注册后在 AppKey 控制台拿到 AppKey，接口地址是 `https://route.showapi.com/1601-2`，把 AppKey 拼在 URL 的 `appKey` 参数上。
- 唯一**必填**参数是 `keyWords`（梦境关键词，如「飞」）；`page` 选填，默认 `1`。
- 业务数据都在 `showapi_res_body` 里：`ret_code` 为 `"0"` 表示成功，`contentlist` 是结果数组，每项含 `name`（梦境名）与 `detailList`（解读文本数组）。
## Why：这跟我有什么关系
你正在做一个娱乐小工具、内容社区，或者只是想在自家产品里加一个「解梦」彩蛋——用户输一句「我梦见被追杀」，你希望立刻返回一段文化解读。这个接口零费用、一个关键词就能查、返回结构干净，非常适合快速嵌入。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口名称 | 免费解梦详细（周公解梦） |
| 接口编码 | 1601（接入点 1601-2 解梦详细） |
| 接口地址 | `https://route.showapi.com/1601-2?appKey={your_appKey}` |
| 请求方式 | POST 或 GET |
| 返回格式 | JSON |
| 是否免费 | 是（注册后默认可免费调用，有档位限制防滥用，具体见[免费档位说明](https://www.showapi.com/free-api)） |
| 必填参数 | `keyWords`（关键词） |
| 选填参数 | `page`（页码，默认 1） |
| 鉴权 | AppKey 放在 URL 的 `appKey` 参数 |
| 接入点说明 | 内容参考《周公解梦全书》部分信息，提供解读参考（文化参考，非科学/医疗结论） |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档 |
前置条件：一个 ShowAPI 账号 + 一个 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)）。
## How：三步跑通
**步骤 1 — 拿 AppKey**：登录后在[我的应用](https://www.showapi.com/console#/myApp)创建应用，复制 AppKey。
**步骤 2 — 发起第一次调用**：以关键词「飞」为例。
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY" # 替换成你的 ShowAPI AppKey
URL = "https://route.showapi.com/1601-2"
resp = requests.post(
URL,
params={"appKey": APP_KEY},
data={"keyWords": "飞", "page": "1"},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
resp.raise_for_status()
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(f"系统错误: {data.get('showapi_res_error')}")
body = data["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(f"业务失败: ret_code={body.get('ret_code')}")
for item in body.get("contentlist", []):
print("梦境:", item.get("name"))
for line in item.get("detailList", []):
print(" -", line)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1601-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "keyWords=%E9%A3%9E&page=1"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const url = `https://route.showapi.com/1601-2?appKey=${APP_KEY}`;
const res = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ keyWords: "飞", page: "1" }),
});
const data = await res.json();
if (data.showapi_res_code !== 0) {
throw new Error("系统错误: " + data.showapi_res_error);
}
const body = data.showapi_res_body;
if (body.ret_code !== "0") {
throw new Error("业务失败: ret_code=" + body.ret_code);
}
for (const item of body.contentlist || []) {
console.log("梦境:", item.name);
(item.detailList || []).forEach((line) => console.log(" -", line));
}
```
**步骤 3 — 解析返回**：详见《[周公解梦 API 返回字段全解](https://www.showapi.com/guides/dream-response-fields-1601)》。
## 返回示例与解析
请求 `keyWords=飞&page=1` 时，接口返回（节选）：
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_body": {
"ret_code": "0",
"contentlist": [
{
"name": "疯子",
"detailList": [
"疯子活在自己的世界里，不受外界环境的干扰，象征着人不会迷失自己，是一种好运。",
"梦见疯子通常预示你将有好运气。"
]
},
{
"name": "疯子追杀我",
"detailList": ["梦见疯子追杀我，要交好运。"]
}
],
"maxResult": 10,
"allNum": 2,
"allPages": 1,
"currentPage": 1
}
}
```
- `showapi_res_code` 是系统级状态码，`0` 表示本次请求成功。
- `showapi_res_body.ret_code` 是业务状态码，`"0"` 表示查询成功。
- `contentlist` 是对象**数组**，每个元素含 `name`（梦境名）与 `detailList`（解读文本数组）。
- `maxResult`/`allNum`/`allPages`/`currentPage` 是分页信息。
## 进阶 / 边界
- **内容是文化参考**：接口说明明确「参考《周公解梦全书》部分信息，提供解读参考」，请勿当作科学或医疗结论向用户呈现。
- **免费但有档位限制**：为防止滥用设有使用档次限制，具体数值见[免费档位说明](https://www.showapi.com/free-api)；同一关键词没必要高频重复请求，建议做短缓存（见《[免费档位与调用限制说明](https://www.showapi.com/guides/dream-free-tier-1601)》）。
- **关键词是单值**：`keyWords` 传一个梦境词即可，传整句话不会自动分词，应先用简单逻辑抽取关键词（见《[关键词怎么查才准](https://www.showapi.com/guides/dream-keywords-guide-1601)》）。
## FAQ
**Q1：返回 `showapi_res_code` 不是 0 怎么办？**
看 `showapi_res_error` 字段的文字说明，通常是签名/AppKey/参数问题，按提示修正后重试。
**Q2：`ret_code` 不是 "0" 是什么意思？**
`ret_code` 只有「0 成功，其余为失败」的约定，文档未枚举具体非零值；非 0 时按失败处理，结合 `showapi_res_error` 排查。
**Q3：免费接口要钱吗？**
注册后默认可免费调用，但有档位限制防滥用；具体档位见[免费档位说明](https://www.showapi.com/free-api)。
**Q4：GET 和 POST 都能用吗？**
都能用。示例用 POST 表单，GET 时把 `keyWords`、`page` 拼到 query 即可（AppKey 始终在 query）。
**Q5：一次能返回多少条？**
由 `maxResult` 控制（示例中为 10），总条数看 `allNum`，总页数看 `allPages`，翻页见《[分页与结果集怎么用](https://www.showapi.com/guides/dream-pagination-1601)》。
## 相关能力 / 下一步阅读
- [周公解梦 API 返回字段全解：ret_code、contentlist、分页字段一文读懂](https://www.showapi.com/guides/dream-response-fields-1601)
- [周公解梦 API：关键词怎么查才准？关键词选取与结果解读实战](https://www.showapi.com/guides/dream-keywords-guide-1601)
- [周公解梦 API 免费档位与调用限制说明：如何避免触发限流？](https://www.showapi.com/guides/dream-free-tier-1601)
- **本系列共 8 篇**：查看[周公解梦 API 指南总目录](https://www.showapi.com/guides/dream-guides-1601)
