长文与批量摘要处理：超时、限流与免费配额的最佳实践
# 长文与批量摘要处理：超时、限流与免费配额的最佳实践
> 接口 961-1 · 免费（受使用档次限制） · 请求方式 POST/GET · 返回格式 JSON · 适用人群：中高级开发者、平台方 · 阅读时间：约 9 分钟
## 核心要点
- 长文建议分段调用：每段独立求摘要，再人工/程序合并，避免单请求过重。
- 客户端超时设 30s（服务器读取超时约 5s，长文生成可能更久）；失败用指数退避重试。
- 「免费」每次仍扣 1 次额度，批量前先算总额，做好限流与配额熔断。
## Why：上线后才发现问题最贵
把接口接进生产，最容易翻车的不是「调不通」，而是「跑批量时额度爆了、长文超时了、并发把账号限了」。本文把这几件事一次讲清，照着做能少很多工单。
## What：接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/961-1?appKey={your_appKey}` |
| 接入点 | `961-1`（仅同步请求/响应，无批量/订阅接入点） |
| 返回 | `showapi_res_body.list` |
| 计费 | 免费，受使用档次限制，每次 `showapi_fee_num=1` |
## How：生产级调用模板（Python）
```python
import time
import requests
APPKEY = "YOUR_APPKEY"
URL = "https://route.showapi.com/961-1"
def summarize(text: str, num: int = 3, max_retries: int = 3) -> list:
for attempt in range(max_retries):
try:
resp = requests.post(
URL,
params={"appKey": APPKEY},
data={"text": text, "num": str(num)},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=30, # 客户端超时，长文留足余量
)
resp.raise_for_status()
data = resp.json()
if str(data.get("showapi_res_code")) != "0":
raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(f"业务失败 ret_code={body.get('ret_code')}")
return body["list"]
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # 指数退避：1s, 2s
return []
def batch_summarize(texts: list, num: int = 3, limit_per_sec: float = 5.0):
"""简易令牌桶限流：每秒最多 limit_per_sec 次"""
interval = 1.0 / limit_per_sec
out = []
for t in texts:
out.append(summarize(t, num))
time.sleep(interval)
return out
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"list": ["提升学习效率", "AI带来的不仅是效率提升", "在制造领域"]
}
}
```
## 进阶 / 边界
- **长文分段策略**：单段建议控制在可稳定返回的长度内；分段后各自调用，再合并 `list`。避免把超长文一次性投递导致超时。
- **超时设置**：服务器读取超时约 5s，但长文生成可能更久；客户端 `timeout` 设 30s 更稳妥。
- **限流与配额熔断**：免费接口每次扣 1 次额度。批量前先估算 `稿件数 × 1`，接近额度上限时暂停并告警；超额需购资源包（[免费 API 说明](https://www.showapi.com/free-api)）。
- **短文本条数少于 `num`**：信息点不足时 `list` 可能少于请求条数，合并/展示前判空。
- **无批量接入点**：本接口只有同步 `961-1`，没有「批量订阅+回调」模型，批量靠自己在客户端循环/队列实现。
## FAQ
**Q1：一次能传多长的 `text`？**
A：公开文档未给明确字符上限；如遇到超时或异常，按上文分段策略处理。
**Q2：免费额度用完了批量任务会怎样？**
A：调用会失败，需购买资源包；建议在任务前校验剩余额度并设置熔断。
**Q3：并发调用会更快吗？**
A：可以并发，但要自带限流，避免触发账号级限制；并发数按额度与稳定性实测确定。
**Q4：失败的请求也扣额度吗？**
A：以 `showapi_fee_num` 实际返回为准；业务失败（`ret_code` 非 0）通常不消耗，但建议以真实返回为准、失败时重试前先确认。
**Q5：要不要做结果缓存？**
A：相同 `text` 反复调用可缓存 `list`（以 `text` 哈希为 key），既提速又省额度。
## 相关能力 / 下一步阅读
- [生成文章摘要参数详解：text 与 num 的正确用法](https://www.showapi.com/guides/article-summary-params-guide-961)
- [新闻媒体如何集成生成文章摘要？从稿件到要点提炼的全链路](https://www.showapi.com/guides/article-summary-news-scenario-961)
- **本系列共 8 篇**：查看[生成文章摘要指南总目录](https://www.showapi.com/guides/article-summary-guides-961)
