# 笑话大全：5 分钟接入，从注册到拿到第一条笑话
> 接口 341-5 · 免费 · POST/GET · JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 笑话大全完全免费，注册 ShowAPI 后拿到 AppKey 即可调用，无需付费。
- 接口没有业务请求参数，只要把 AppKey 拼到请求地址就能拿到一条随机笑话。
- 真正要展示的文字在 `showapi_res_body.text`；`ret_code = 0` 表示成功。
## Why
你在运营一个博客、论坛或公众号，想要一个"每日一笑"小模块帮用户放松、顺便降低跳出率。自己维护笑话库成本高、更新慢；而 ShowAPI 的**笑话大全**接口注册即免费可用，每次调用随机返回一条笑话，非常适合做轻量引流组件。
本篇目标：让你在 5 分钟内跑通"注册 → 取 AppKey → 第一次调用 → 拿到笑话文字"，不纠结任何高级概念。
## What
| 项 | 说明 |
|----|------|
| 接口地址 | `https://route.showapi.com/341-5` |
| 接入点 | 341-5 随机生成文本笑话（默认分组，仅此 1 个） |
| 请求方式 | POST 或 GET 均可 |
| 鉴权 | URL 中 `appKey` 参数（从[控制台](https://www.showapi.com/console#/myApp)获取） |
| 业务参数 | 无（OpenAPI `parameters: []`） |
| 返回格式 | JSON，业务数据在 `showapi_res_body` 内 |
| 计费 | 免费（有使用档位限制防滥用，具体见[免费 API 说明](https://www.showapi.com/free-api)） |
前置条件：一个 ShowAPI 账号 + 一个 AppKey。没有就先去[注册](https://www.showapi.com/console#/myApp)。
## How
### 步骤 1：拿到 AppKey
登录 ShowAPI 控制台 →「我的应用」→ 复制 AppKey。下文用 `YOUR_APPKEY` 占位，替换成你自己的即可。
### 步骤 2：发起第一次调用
下面三种写法任选其一，**替换 AppKey 即可直接运行**。
**Python（requests）**
```python
import requests
APP_KEY = "YOUR_APPKEY" # 替换为你的 ShowAPI AppKey
resp = requests.post(
"https://route.showapi.com/341-5",
params={"appKey": APP_KEY},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=20,
)
data = resp.json()
body = data.get("showapi_res_body", {})
if body.get("ret_code") == 0:
print("标题：", body.get("title"))
print("内容：", body.get("text"))
else:
print("调用失败：", body.get("remark"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/341-5?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded"
```
**Node.js（fetch）**
```javascript
const APP_KEY = "YOUR_APPKEY";
const resp = await fetch(`https://route.showapi.com/341-5?appKey=${APP_KEY}`, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
});
const data = await resp.json();
const body = data.showapi_res_body || {};
if (body.ret_code === 0) {
console.log("标题：", body.title);
console.log("内容：", body.text);
} else {
console.log("调用失败：", body.remark);
}
```
### 步骤 3：解析并展示
返回里**只有 `showapi_res_body` 里的内容是笑话本身**。`text` 是要展示的笑话正文；`title` 是分类标题（注意文档标注"会重复"，展示时可不必强依赖）；`ret_code` 为 `0` 才代表成功。
## 返回示例与解析
```json
{
"showapi_res_error": "",
"showapi_fee_num": 1,
"showapi_res_code": 0,
"showapi_res_id": "69aa6d3cfb638c5c252249e7",
"showapi_res_body": {
"id": "69a921a1530719e3c602fe0b",
"title": "讽刺、荒唐的爆笑事儿",
"text": "博士毕业两年多，父母从老家来看我……",
"ret_code": 0,
"remark": "查询成功！",
"ct": "2026-03-05 14:24:33.420"
}
}
```
| 字段 | 层级 | 含义 |
|------|------|------|
| `showapi_res_code` | 系统级 | API 整体状态码，0 一般表示网关正常 |
| `showapi_res_body` | 系统级 | 业务数据容器，笑话都在里面 |
| `id` | 业务体 | 本条笑话唯一 id |
| `title` | 业务体 | 标题（会重复，可不展示） |
| `text` | 业务体 | 笑话正文，真正要显示的内容 |
| `ret_code` | 业务体 | `0`=成功，其他=失败 |
| `remark` | 业务体 | 返回描述，如"查询成功！" |
| `ct` | 业务体 | 返回时间 |
字段完整说明见[笑话大全返回字段全解](https://www.showapi.com/guides/joke-api-response-fields-341)。
## 进阶 / 边界
- **GET 也能调**：把 `appKey` 放 query 即可，POST/GET 二选一。
- **免费但有档位**：高频刷会触发使用档次限制，做生产请加缓存（见[缓存与档位限制应对](https://www.showapi.com/guides/joke-api-cache-tier-341)）。
- **内容是随机的**：同一次响应里的 `title` 可能重复，不要把它当唯一主键。
## FAQ
**Q1：接口真的免费吗？要不要充值？**
免费。注册后默认即可调用；为防止滥用设有使用档次限制，具体额度以[免费 API 说明](https://www.showapi.com/free-api)为准，无需先充值。
**Q2：调用一定要传业务参数吗？**
不需要。接口没有业务请求参数，鉴权只用 URL 里的 `appKey`。
**Q3：每次返回的都是同一条笑话吗？**
不是。每次调用内容随机变化；但 `title`（分类标题）字段文档明确标注"会重复"，属正常现象。
**Q4：返回的 text 为什么有时很短？**
笑话内容由数据源随机给出，长短不一，属正常；如需控制展示样式，可在前端做截断或"换一条"按钮重新调用。
**Q5：AppKey 能写在前端代码里吗？**
不建议。AppKey 等同于凭证，前端暴露有被盗用风险；网站集成请用后端代理转发（见[博客集成](https://www.showapi.com/guides/joke-api-blog-daily-341)）。
## 相关能力 / 下一步阅读
- [笑话大全返回字段全解：showapi_res_body 与 id/title/text 一文读懂](https://www.showapi.com/guides/joke-api-response-fields-341)
- [博客/论坛集成笑话大全：用"每日一笑"降低跳出率](https://www.showapi.com/guides/joke-api-blog-daily-341)
- [免费接口也要讲边界：笑话大全缓存策略与档位限制应对](https://www.showapi.com/guides/joke-api-cache-tier-341)
- **本系列共 10 篇**：查看[笑话大全 API 指南总目录](https://www.showapi.com/guides/joke-api-guides-341)
