中文近义词反义词 API：免费接口的缓存与频率最佳实践
中文近义词API中文反义词API免费接口ShowAPI # 中文近义词反义词 API：免费接口的缓存与频率最佳实践
> 接口：免费近义词 - 中文近义词和反义词（apiCode=1624）· 免费服务 · POST/GET · 适用人群：已接入用户、后端工程师 · 阅读时间：约 5 分钟
## 核心要点
- "免费"不等于"无限"：每次调用实测 `showapi_fee_num=1`，从免费额度扣除 1 计量。
- 词语的近义/反义关系语义稳定，相同 `keyWords` 的返回可本地缓存，减少重复调用。
- 调用前做基础校验（空词、超长词），避免无效请求浪费额度。
## Why：这跟你有什么关系
接口免费很容易让人无脑狂调，等到额度用完才发现。其实大多数应用场景里，同一个词会被反复查询（比如同一篇文档多次润色、同一张词卡多次打开）。加上一层本地缓存和简单校验，就能把调用量压下去，既省钱又更快。
## What：计费与额度事实
| 项目 | 说明 |
|------|------|
| 计费标注 | 免费服务 |
| 实测消耗 | 每次调用 `showapi_fee_num=1`（从免费额度扣 1 计量） |
| 近义+反义 | 分别调用 `1624-1` 与 `1624-2`，合计 2 计量/词 |
| 更新频率 | 数据持续更新中（语义关系相对稳定） |
> 文档未提供具体额度上限与档位数字，请以[平台额度说明](https://www.showapi.com/console#/myApp)为准，本文不编造数字。
## How：带缓存的查询封装（Python）
```python
import requests
APP_KEY = "YOUR_APPKEY"
CACHE = {} # 词语语义稳定，可复用结果
def query(point: str, word: str):
word = (word or "").strip()
if not word:
raise ValueError("keyWords 不能为空")
if len(word) > 50: # 基础校验，避免异常长输入
raise ValueError("keyWords 过长")
cache_key = (point, word)
if cache_key in CACHE:
return CACHE[cache_key]
resp = requests.post(
f"https://route.showapi.com/{point}",
params={"appKey": APP_KEY},
data={"keyWords": word},
headers={"content-type": "application/x-www-form-urlencoded"},
timeout=10,
)
data = resp.json()
if data.get("showapi_res_code") != 0:
raise RuntimeError(data.get("showapi_res_error"))
body = data["showapi_res_body"]
if body.get("ret_code") != 0:
raise RuntimeError(body.get("remark"))
result = [{"word": i["words"], "detail": i["wordsDetail"]} for i in body["result"]]
CACHE[cache_key] = result # 写入缓存，后续同源查询不再发请求
return result
```
缓存可替换为基础内存字典、Redis 或本地文件，按服务规模选择；键建议包含接入点与点（如 `1624-1:残酷`）。
## 返回示例与解析（真实返回，已精简）
```json
{
"showapi_res_code": 0,
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": 0,
"result": [
{"words": "严酷", "wordsDetail": "[ yán kù ] （形）①严厉；严格：～的教训。②残酷；冷酷：～的剥削。"}
]
}
}
```
字段含义见[返回结构全解](https://www.showapi.com/guides/chinese-synonym-antonym-response-codes-1624)。
## 进阶 / 边界
- 缓存有效期：语义关系稳定，可设较长 TTL（如 7~30 天）；若需紧跟"持续更新"，可设较短 TTL 或按需刷新。
- 无效请求拦截：空 `keyWords`、纯标点、超长串在客户端先校验，不发起请求。
- 批量场景：逐词调用时先查本地缓存再决定是否发请求，可显著降低总调用量。
- 限流：虽文档未给出限速值，建议对高频来源加令牌桶/队列，避免突发打满额度。
## FAQ
**Q1：免费接口为什么还要在意调用次数？**
A：免费接口每次调用仍消耗 1 计量（`showapi_fee_num=1`），额度用尽后可能影响使用，故应尽量减少无效/重复调用。
**Q2：缓存安全吗？语义会变吗？**
A：词语近义/反义关系相对稳定，本地缓存风险低；接口标注"数据持续更新中"，可按需设 TTL 刷新。
**Q3：额度上限是多少？**
A：文档未提供具体上限数字，请以[平台额度说明](https://www.showapi.com/console#/myApp)为准，本文不编造。
**Q4：近义+反义一次词要几次调用？**
A：两次（1624-1 与 1624-2 各一次，合计 2 计量）；若两者都命中缓存则 0 次。
## 相关能力 / 下一步阅读
- [中文近义词反义词 API：返回结构全解（ret_code 与 result 数组）](https://www.showapi.com/guides/chinese-synonym-antonym-response-codes-1624)
- [中文近义词反义词 API：语文词汇学习场景集成](https://www.showapi.com/guides/chinese-synonym-antonym-edu-vocab-1624)
- **本系列共 8 篇**：查看[中文近义词反义词 API 使用指南总目录](https://www.showapi.com/guides/chinese-synonym-antonym-guides-1624)
