免费名言警句：5 分钟接入，从注册到第一条名言
免费名言警句API快速接入Python示例每日一句 # 免费名言警句：5 分钟接入，从注册到第一条名言
> 接口 1839-1 · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 免费名言警句接口注册后默认可免费调用，无需付费即可拿到第一条名言。
- 只需一个参数 `num`（最多 10 条，可省略），拼上接口地址与 AppKey 即可请求。
- 返回数据是 `showapi_res_body.contentlist` 数组，每项 `content` 是一句带作者的名言。
## Why
在网站首页、App 开屏、教育类产品的"每日一句"、社群机器人的随机激励文案里，一句恰当的名言能显著提升质感。过去你要自己维护一个名言库、担心版权和时效；现在调一个免费接口就能拿到经过整理的名言警句。
本文带你用 5 分钟跑通第一条请求——从注册、拿密钥，到发起调用、解析返回，最后在页面上展示出来。
## What
**前置条件**
- 已在 [showapi.com](https://www.showapi.com) 注册账号
- 在控制台拿到 AppKey（[AppKey 管理](https://www.showapi.com/console#/myApp)）
- 运行环境能访问 `route.showapi.com`
**接口速览**
| 项 | 值 |
|----|----|
| 请求地址 | `https://route.showapi.com/1839-1?appKey=YOUR_APPKEY` |
| 请求方式 | POST 或 GET |
| 请求参数 | `num`（String，最多 10 条，非必填） |
| 返回格式 | JSON，业务数据位于 `showapi_res_body` |
| 计费 | 免费（有使用档位限制，具体见[免费 API 页](https://www.showapi.com/free-api)） |
## How
### 步骤 1：获取 AppKey
登录后进入 [控制台 → 我的应用](https://www.showapi.com/console#/myApp)，复制你的 AppKey，下文用 `YOUR_APPKEY` 占位。
### 步骤 2：发起第一次调用（取 3 条为例）
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/1839-1"
params = {"appKey": "YOUR_APPKEY", "num": "3"} # num 最多 10 条，可省略
try:
r = requests.get(url, params=params, timeout=15)
r.raise_for_status()
data = r.json()
except Exception as e:
print("请求失败：", e)
raise
body = data.get("showapi_res_body", {})
if body.get("ret_code") != "0":
print("接口返回错误：", body.get("remark"))
else:
for item in body.get("contentlist", []):
print(item.get("content"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1839-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "num=3"
```
**Node.js（fetch）**
```javascript
const url = "https://route.showapi.com/1839-1?appKey=YOUR_APPKEY";
fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: "num=3",
signal: AbortSignal.timeout(15000),
})
.then((r) => r.json())
.then((data) => {
const body = data.showapi_res_body;
if (body.ret_code !== "0") {
console.error("接口错误：", body.remark);
return;
}
body.contentlist.forEach((it) => console.log(it.content));
})
.catch((e) => console.error("请求失败：", e));
```
### 步骤 3：解析 contentlist
返回里真正有用的内容是 `showapi_res_body.contentlist` 数组，每一项是一个对象，字段 `content` 就是"名言 + 作者"的字符串（例如 `因天下之力，以生天下之财；取天下之财，以供天下之费。王安石（宋）`）。直接遍历即可展示。
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"allNum": 3,
"allPages": 1,
"contentlist": [
{ "content": "德盛者威广，力盛者骄众。齐桓公尚德以霸，秦二世尚刑而亡。——陆贾" },
{ "content": "一名伟大的球星最突出的能力就是让周围的队友变得更好。--迈克尔·乔丹" },
{ "content": "因天下之力，以生天下之财；取天下之财，以供天下之费。王安石（宋）" }
],
"currentPage": 1,
"maxResult": 3,
"remark": "查询成功！",
"ret_code": "0"
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_body.ret_code` | String | `"0"` 成功，其他为失败 |
| `showapi_res_body.remark` | String | 提示信息，如"查询成功！" |
| `showapi_res_body.contentlist` | Object[] | 内容列表，每项含 `content` |
| `showapi_res_body.contentlist[].content` | String | 名言 + 作者（合并字符串） |
| `showapi_res_body.maxResult` | String | 当前页最大值（等于 `num`） |
| `showapi_res_body.currentPage` | String | 当前页码（默认 1） |
| `showapi_res_body.allPages` | String | 页码数 |
| `showapi_res_body.allNum` | String | 内容条数 |
## 进阶 / 边界
- **返回是随机名言**，无法指定标签/作者/主题（官方描述与真实参数不一致，当前仅支持 `num` 控制条数）。
- **作者内嵌**在 `content` 字符串中（如"王安石（宋）"），如需独立展示需自行按标点拆分。
- 免费接口有使用档位限制，超限表现见 FAQ。
## FAQ
**Q1：一定要传 `num` 吗？**
A：不必。`num` 非必填；不传时接口按默认条数返回（返回示例中 `maxResult` 等于你传入的 `num`，省略则取接口默认）。
**Q2：返回是固定的还是随机的？**
A：每次调用返回随机挑选的名言，适合"每日一句""随机激励"这类场景；不适合需要固定某句或按主题归类的需求。
**Q3：免费接口有调用上限吗？**
A：注册后默认可免费调用，但为防止滥用设有使用档次限制，具体档位以[免费 API 页](https://www.showapi.com/free-api)为准。
**Q4：支持按作者或主题筛选吗？**
A：当前不支持。真实请求参数只有 `num`，没有 tag/author/theme 类筛选参数。
## 相关能力 / 下一步阅读
- [免费名言警句：返回字段全解（contentlist / ret_code / allNum）](https://www.showapi.com/guides/famous-quotes-response-fields-1839)
- [免费名言警句：num 参数怎么用？最多 10 条与"随机返回"机制](https://www.showapi.com/guides/famous-quotes-num-param-1839)
- [免费名言警句：多语言调用示例（Python / Java / Go / Node.js）](https://www.showapi.com/guides/famous-quotes-multilang-1839)
- **本系列共 10 篇**：查看[免费名言警句指南总目录](https://www.showapi.com/guides/famous-quotes-guides-1839)
