生成文章摘要参数详解：text 与 num 的正确用法
# 生成文章摘要参数详解：text 与 num 的正确用法
> 接口 961-1 · 免费（受使用档次限制） · 请求方式 POST/GET · 返回格式 JSON · 适用人群：所有调用方 · 阅读时间：约 6 分钟
## 核心要点
- 只有两个必填参数：`text`（文章正文）和 `num`（期望的摘要条数），其余均可不传。
- `num` 是「期望条数」而非「保证条数」：原文太短、信息点不足时，实际返回可能少于 `num`。
- `text` 可能很长，强烈建议用 POST，避免 GET 的 URL 长度限制。
## Why：参数用错是最常见的失败来源
很多「调用失败」或「摘要不对劲」，根因都在参数：`num` 传成数字类型、`text` 为空、或用 GET 拼超长中文。把这两个参数讲清楚，能挡掉大部分工单。
## What：参数速览
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| `text` | body | String | 是 | 文章正文 |
| `num` | body | String | 是 | 生成的摘要条目数（传字符串，如 `"3"`） |
| `content-type` | Header | String | 否 | 表单提交用 `application/x-www-form-urlencoded` |
| `appKey` | query | String | 是 | 鉴权，从控制台获取 |
## How：正确传参
```python
import requests
APPKEY = "YOUR_APPKEY"
resp = requests.post(
"https://route.showapi.com/961-1",
params={"appKey": APPKEY},
data={
"text": "在这里粘贴你的文章正文，可以很长……",
"num": "3", # 字符串类型
},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=30,
)
data = resp.json()
body = data.get("showapi_res_body", {})
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务失败 ret_code={body.get('ret_code')}")
print(body["list"])
```
cURL 务必用 `--data-urlencode` 处理中文：
```bash
curl -X POST "https://route.showapi.com/961-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
--data-urlencode "text=在这里粘贴你的文章正文……" \
--data-urlencode "num=3"
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_id": "6a978509fb638c36635deabe",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"list": ["提升学习效率", "AI带来的不仅是效率提升", "在制造领域"]
}
}
```
## 进阶 / 边界
- **`num` 与返回条数的关系（实测）**：较长文本 `num=3` → 返回 3 条、`num=5` → 返回 5 条；但短文本 `num=3` 实测仅返回 1 条。结论：**实际条数 ≤ num，取决于原文长度与信息密度**。前端展示前务必判空、做兜底文案。
- **`text` 为空或缺失**：属于必填项，缺失时业务会失败（`ret_code` 非 0），调用前做非空校验。
- **`num` 的类型**：文档/OpenAPI 中 `num` 为 String，传 `"3"` 这类字符串；不要传成数字 `3` 以免部分客户端序列化异常。
- **GET 的限制**：`text` 很长时 GET 的 URL 长度受限且中文需编码，推荐统一用 POST。
## FAQ
**Q1：`num` 最大能传多少？**
A：公开文档未给出上限值，建议从较小值（如 3~10）起步实测；如返回条数异常，先排查原文长度与信息量。
**Q2：为什么我传 `num=5` 只回来 2 条？**
A：原文信息点不足时接口只会返回它能提炼出的要点，实际条数可能少于 `num`，属正常行为。
**Q3：`text` 有长度上限吗？**
A：公开文档未给出明确字符上限；长文建议分段处理（见 [长文与批量摘要处理](https://www.showapi.com/guides/article-summary-batch-961)）。
**Q4：两个参数必须一起传吗？**
A：是，`text` 和 `num` 都为必填，缺一不可。
**Q5：可以只传 `text` 让接口自己决定条数吗？**
A：不可以，`num` 为必填，需显式指定期望条数。
## 相关能力 / 下一步阅读
- [生成文章摘要返回字段全解：showapi_res_body 与 list / ret_code 一文读懂](https://www.showapi.com/guides/article-summary-response-fields-961)
- [长文与批量摘要处理：超时、限流与免费配额的最佳实践](https://www.showapi.com/guides/article-summary-batch-961)
- **本系列共 8 篇**：查看[生成文章摘要指南总目录](https://www.showapi.com/guides/article-summary-guides-961)
