免费名言警句：num 参数怎么用？最多 10 条与"随机返回"机制
# 免费名言警句：num 参数怎么用？最多 10 条与"随机返回"机制
> 接口 1839-1 · 免费 · 请求方式 POST/GET · 返回 JSON · 适用人群：准备按需求取数的开发者 · 阅读时间：约 4 分钟
## 核心要点
- 接口唯一业务参数是 `num`：控制一次返回多少条，最多 10 条，非必填。
- 返回的 `contentlist` 是**随机挑选**的名言，不是按你指定的分类、作者或主题。
- 官方页面/文档描述写有"可按标签、作者、主题筛选"，但真实请求参数里**没有**这类筛选参数——本文如实澄清。
## Why
你大概率会想："我想给健身 App 推励志格言、给国学栏目推古人名句。"但看完接口你会发现，它并不接受"分类"参数——它只负责随机给你 N 条名言。理解这一点，才能正确设计产品（比如用本地分类标签去匹配返回名言，而不是指望接口筛）。
本文把 `num` 的真实用法讲透，并明确接口的能力边界，避免你在"按主题筛选"上白费功夫。
## What
**接口速览**
| 项 | 值 |
|----|----|
| 请求参数 | `num`（String，最多 10 条，非必填） |
| Header | `content-type: application/x-www-form-urlencoded`（非必填） |
| 其他参数 | 无（真实参数仅 `num`，**无** tag/author/theme/keyword） |
| 返回条数 | 等于 `num`（不超过 10） |
## How
### 步骤 1：用 num 控制条数
```python
import requests
def get_quotes(num: int = 3):
r = requests.get(
"https://route.showapi.com/1839-1",
params={"appKey": "YOUR_APPKEY", "num": str(min(num, 10))},
timeout=15,
)
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
raise RuntimeError(body.get("remark"))
return [it["content"] for it in body["contentlist"]]
print(get_quotes(5)) # 最多 10 条，超出按 10 处理
```
### 步骤 2：理解"随机返回"机制
每次调用返回随机挑选的名言，`content` 形如 `"名言正文。作者（朝代）"`。同一个 `num` 连续调用，结果通常不同。接口**没有**用于指定分类、作者、主题的入参。
## 返回示例与解析
```json
{
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"maxResult": "5",
"currentPage": "1",
"allPages": "1",
"allNum": "5",
"contentlist": [
{ "content": "一名伟大的球星最突出的能力就是让周围的队友变得更好。--迈克尔·乔丹" }
]
}
}
```
- `maxResult` 等于你传入的 `num`（本例 5）。
- `contentlist` 长度为 `num`（不超过 10）。
## 进阶 / 边界
- **不支持按分类/作者/主题筛选**：页面与 OpenAPI 描述提到"可按标签、作者、主题筛选"，但 OpenAPI 的 `parameters` 为空、requestBody 仅含 `num`。这属于文档描述与真实能力不一致，规划产品时请以真实参数为准。
- **想要"主题化"怎么办**：在本地维护一个分类标签表，或对接其它支持分类的语料，再用本接口做"随机填充"；不要依赖接口侧筛选。
- `num` 传大于 10 的值不会被接受（以最多 10 条为上限），建议客户端先 `min(num, 10)` 兜底。
## FAQ
**Q1：能一次要 20 条吗？**
A：不能，`num` 最多 10 条。需要更多时只能多次调用（注意免费档位限制）。
**Q2：能指定只要"励志"类或"某位作者"的吗？**
A：当前不能。接口只支持 `num` 控制条数，无分类/作者/主题筛选参数。
**Q3：为什么两次调用结果不一样？**
A：接口随机返回，适合"每日一句""随机激励"；若需固定内容，应在你侧缓存首次结果。
**Q4：作者信息怎么单独取？**
A：作者内嵌在 `content` 字符串里（多以"——""--"或"（朝代）"结尾），需自行用正则/字符串分割提取。
## 相关能力 / 下一步阅读
- [免费名言警句：返回字段全解（contentlist / ret_code / allNum）](https://www.showapi.com/guides/famous-quotes-response-fields-1839)
- [免费名言警句：如何设计缓存策略，避免重复调用浪费免费档位](https://www.showapi.com/guides/famous-quotes-cache-1839)
- [免费名言警句：常见问题与排查（ret_code 非 0 / 返回为空 / 免费档位限制）](https://www.showapi.com/guides/famous-quotes-faq-1839)
- **本系列共 10 篇**：查看[免费名言警句指南总目录](https://www.showapi.com/guides/famous-quotes-guides-1839)
