童话故事集 API：5 分钟接入，从注册到读出第一篇故事
# 童话故事集 API：5 分钟接入，从注册到读出第一篇故事
> 元信息：童话故事集 API（apiCode=1700）· 免费服务 · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者、家长向应用开发者 · 阅读时间约 6 分钟
## 核心要点
- 三个接入点串成一条链路：分类(1700-1) → 列表(1700-2) → 详情(1700-3)，后两步依赖前一步返回的 classifyId / id。
- 免费接口，注册后取 AppKey 即可调用；请求走 `route.showapi.com/1700-x?appKey=YOUR_APPKEY`。
- 判断成功看业务字段 `showapi_res_body.ret_code == "0"`，系统级错误看 `showapi_res_code`。
## Why：这跟你有什么关系
如果你想做一个给孩子讲睡前故事的小程序、一个绘本阅读页面，或者只是想在 AI 客户端里让孩子随口点一个故事听，你不需要自己去找版权内容、搭内容库。童话故事集 API 已经把安徒生童话、格林童话、成语故事、寓言故事等经典内容整理好，按「分类 → 列表 → 详情」三步取用即可。
本篇目标：不依赖任何框架，用最少的代码把整条链路跑通，让你 5 分钟内读到第一篇故事正文。
## What：前置条件与接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/1700-1?appKey=YOUR_APPKEY`（分类）/ `-2`（列表）/ `-3`（详情） |
| 接入点 | 1700-1 故事分类、1700-2 故事列表、1700-3 故事详情 |
| 请求方式 | POST 或 GET |
| 鉴权 | URL query 参数 `appKey` |
| 计费 | 免费（有使用档次限制，见档位说明） |
| 集成能力 | MCP 服务、OpenAPI 3.0 文档 |
前置条件：
1. 注册 ShowAPI 账号并登录。
2. 在「我的应用」创建一个应用，拿到 AppKey（https://www.showapi.com/console#/myApp）。
## How：三步跑通
### 第一步：取分类（1700-1）
请求无业务参数，直接调用即可。
```python
import requests, json
APPKEY = "YOUR_APPKEY"
url = f"https://route.showapi.com/1700-1?appKey={APPKEY}"
r = requests.post(url, headers={"content-type": "application/x-www-form-urlencoded"}, timeout=10)
data = r.json()
body = data.get("showapi_res_body", {})
if body.get("ret_code") != "0":
raise SystemExit(f"接口返回失败：{body.get('remark')}")
for item in body.get("storylist", []):
print(item["classifyId"], item["classify"])
```
```bash
curl -X POST "https://route.showapi.com/1700-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
```javascript
const APPKEY = "YOUR_APPKEY";
const r = await fetch(`https://route.showapi.com/1700-1?appKey=${APPKEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
});
const data = await r.json();
const body = data.showapi_res_body;
if (body.ret_code !== "0") throw new Error(body.remark);
for (const item of body.storylist) console.log(item.classifyId, item.classify);
```
### 第二步：按分类+关键字取列表（1700-2）
`classifyId` 与 `keyword` 均为必填，`page` 可选（默认第 1 页）。
```python
params = {"classifyId": "1", "keyword": "妈妈", "page": "1"}
r = requests.post(f"https://route.showapi.com/1700-2?appKey={APPKEY}", data=params, timeout=10)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise SystemExit(f"失败：{body.get('remark')}")
for item in body.get("contentlist", []):
print(item["id"], item["title"], "分类:", item["classifyId"])
```
```bash
curl -X POST "https://route.showapi.com/1700-2?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "classifyId=1&page=1&keyword=%E5%A6%88%E5%A6%88"
```
```javascript
const r = await fetch(`https://route.showapi.com/1700-2?appKey=${APPKEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ classifyId: "1", keyword: "妈妈", page: "1" }),
});
const body = (await r.json()).showapi_res_body;
if (body.ret_code !== "0") throw new Error(body.remark);
for (const item of body.contentlist) console.log(item.id, item.title);
```
### 第三步：用 id 取详情（1700-3）
`id` 来自上一步 `contentlist[].id`。
```python
story_id = body["contentlist"][0]["id"]
r = requests.post(f"https://route.showapi.com/1700-3?appKey={APPKEY}",
data={"id": story_id}, timeout=10)
body = r.json()["showapi_res_body"]
print("标题:", body["title"])
print("分类:", body["classify"])
print("正文前 80 字:", body["content"][:80])
```
```bash
curl -X POST "https://route.showapi.com/1700-3?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "id=5ba1c5bfc1b4be0a124a8445"
```
```javascript
const r = await fetch(`https://route.showapi.com/1700-3?appKey=${APPKEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({ id: "5ba1c5bfc1b4be0a124a8445" }),
});
const body = (await r.json()).showapi_res_body;
console.log(body.title, body.content);
```
## 返回示例与解析
1700-1 返回结构（注意：真实返回是 `storylist[]` 数组，文档字段表与之存在命名差异，以真实结构为准）：
```json
{
"showapi_res_code": 0,
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"storylist": [
{ "classify": "儿童小故事", "classifyId": "1" },
{ "classify": "安徒生童话", "classifyId": "2" }
]
}
}
```
关键字段：
- `showapi_res_code`：系统级状态码，0 成功。
- `showapi_res_body.ret_code`：业务状态码，"0" 成功，其他失败。
- `showapi_res_body.remark`：提示信息，如「查询成功！」。
## 进阶 / 边界
- 链路依赖：1700-2 的 `classifyId` 取自已 1700-1；1700-3 的 `id` 取自已 1700-2。生产代码里建议把这些 id 存数据库，不要每次实时拉。
- `keyword` 必填：1700-2 的 `keyword` 是必填项（详见[列表实战](https://www.showapi.com/guides/child-story-list-guide-1700)）。「查全部分类内容」的空值行为文档未给出，不要臆测，建议实测。
- 免费有限流：大批量循环调用可能触发档次限制（见[免费档位说明](https://www.showapi.com/guides/child-story-free-tier-1700)）。
## FAQ
**Q: 返回里既有 showapi_res_code 又有 showapi_res_body.ret_code，以哪个为准？**
A: 业务是否成功以 `showapi_res_body.ret_code == "0"` 为准；`showapi_res_code` 是系统级封装状态。两者都建议判断。
**Q: keyword 必填，那只想按分类浏览全部故事怎么办？**
A: 文档未给出"查全部"的空值约定，不要硬编码空格或通配。建议先用一个常见关键字拉取，或等官方明确，避免臆造行为。
**Q: 接口免费，还需要 AppKey 吗？**
A: 需要。免费服务仍需注册并创建应用拿到 AppKey，靠 AppKey 做鉴权与档次统计。
**Q: POST 和 GET 都能用吗？**
A: 都能用。示例用 POST，参数放 body（form 表单）；GET 时把参数拼到 URL query 即可。
## 相关能力 / 下一步阅读
- [童话故事集 API 返回字段全解](https://www.showapi.com/guides/child-story-fields-1700)
- [童话故事集 API：故事列表搜索与分页实战](https://www.showapi.com/guides/child-story-list-guide-1700)
- [通过 MCP 在 AI 客户端里直接调用童话故事集 API](https://www.showapi.com/guides/child-story-mcp-1700)
- **本系列共 12 篇**：查看[童话故事集 API 指南总目录](https://www.showapi.com/guides/child-story-guides-1700)
