# 藏头诗生成：免费档位与积分兑换，如何控制调用成本
> 接口/接入点：藏头诗生成（apiCode=950，接入点 950-1）· 免费 · 返回格式 JSON · 适用人群：已接入用户、运营、开发者 · 阅读时间：7 分钟
## 核心要点
- 接口**免费**，注册后默认可调用，但"为防止滥用设有使用档次限制"。
- 权益档次可用平台积分兑换更高调用档位；**具体档位数字文档未给**，以官方档位说明为准。
- 相同 key+参数结果可在本地缓存，减少重复调用、规避限流。
## Why：免费不等于无限，懂得控成本才稳
免费接口对调用量有档次限制，业务一旦放量（如节日群发）容易被限。理解档位机制 + 做好缓存，才能在"零成本"前提下稳定服务。
## What：计费与档位事实
| 项目 | 说明（来自文档） |
|------|------|
| 是否免费 | 是，注册后默认可免费调用 |
| 限制 | 为防止滥用设有使用档次限制（具体档位见官方说明） |
| 提升额度 | 权益档次可使用平台积分兑换更高调用档位 |
| 具体数字 | 文档未给出档位/价格，**不编造**，以[官方档位说明](https://www.showapi.com/free-api)为准 |
> 本接口无"按次计费"字段暴露给调用方（`showapi_fee_num` 在 OpenAPI 中定义为计费次数，免费场景一般不计）。
## How：本地缓存省调用
相同 key+num+type+yayuntype 组合结果可缓存。下面用内存字典示例，生产可换 Redis。
**Python（内存缓存）**
```python
import requests
cache = {}
def gen_poem(key, num="5", t="1", y="1"):
pk = (key, num, t, y)
if pk in cache:
return cache[pk] # 命中缓存，不调用
url = "https://route.showapi.com/950-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"num": num, "type": t, "yayuntype": y, "key": key}
r = requests.post(url, params=params, data=data, timeout=30)
body = r.json().get("showapi_res_body", {})
poems = body.get("list", []) if body.get("ret_code") == "0" else []
cache[pk] = poems
return poems
print(gen_poem("易源接口")) # 调用一次
print(gen_poem("易源接口")) # 命中缓存
```
**Node.js（Map 缓存）**
```javascript
const cache = new Map();
async function genPoem(key, num = "5", t = "1", y = "1") {
const pk = `${key}|${num}|${t}|${y}`;
if (cache.has(pk)) return cache.get(pk);
const body = new URLSearchParams({ num, type: t, yayuntype: y, key });
const resp = await fetch("https://route.showapi.com/950-1?appKey=YOUR_APPKEY",
{ method: "POST", body, signal: AbortSignal.timeout(30000) });
const res = await resp.json();
const b = res.showapi_res_body;
const poems = b.ret_code === "0" ? b.list : [];
cache.set(pk, poems);
return poems;
}
```
## 返回示例与解析
缓存逻辑不改变返回结构：`showapi_res_body.list` 仍为诗句数组；只是相同请求不再重复发起 HTTP 调用，从而节省免费档位额度。
## 进阶 / 边界
- **档位数字不臆造**：本文未写具体调用上限/价格，因为这些未在文档给出；接入前请查[官方档位说明](https://www.showapi.com/free-api)。
- **批量场景先缓存**：节日群发给多人时，重复名字先查缓存，见[节日祝福批量实战](https://www.showapi.com/guides/cangtoushi-blessing-950)。
- **重试也计费注意力**：失败重试会消耗额度，重试务必加指数退避，见[错误处理与超时](https://www.showapi.com/guides/cangtoushi-error-handle-950)。
## FAQ
**Q1：免费能调多少次？** 文档未给具体数字，以官方档位说明为准，不要凭印象估算。
**Q2：积分怎么换更高档位？** 通过平台积分兑换权益档次，详情见官方档位说明页。
**Q3：缓存 key 怎么设计？** 用全部影响结果的参数组合（key+num+type+yayuntype）做键，确保命中正确。
**Q4：缓存会过期吗？** 诗句为确定性生成时可长期缓存；若需"每次不同"则不缓存，按业务取舍。
## 相关能力 / 下一步阅读
- [藏头诗生成：错误处理与超时（ret_code / showapi_res_code / 30s 超时）](https://www.showapi.com/guides/cangtoushi-error-handle-950)
- [藏头诗生成：节日祝福藏头诗批量生成实战](https://www.showapi.com/guides/cangtoushi-blessing-950)
- **本系列共 12 篇**：查看[藏头诗生成指南总目录](https://www.showapi.com/guides/cangtoushi-guides-950)
