图片水印裁剪缩略接口：免费档位限制与频率控制，如何避免触发限流
# 图片水印裁剪缩略接口：免费档位限制与频率控制，如何避免触发限流
> 接口/接入点：图片水印裁剪缩略接口（apiCode=1）· 全部接入点 · 是否免费：免费（有使用档次限制） · 请求方式：POST/GET · 返回格式：JSON · 适用人群：中高级开发者、架构师 · 阅读时间：7 分钟
## 核心要点
- 接口免费但「有使用档次限制」防滥用；具体档位/频率数字文档未给，以实际返回 `ret_code` 非 0 为限流信号。
- 客户端做频率控制（令牌桶/节流）+ 指数退避重试 + 结果本地缓存，是稳定调用的三板斧。
- 同一原图不要重复调，生成结果落库复用最省钱（这里省的是调用额度）。
## Why：免费为什么还要控频
免费不代表无限。档位限制是为了防止单用户刷爆服务。一旦超限，调用返回失败、业务图出不来。做好频率与缓存，既能稳定出图，也避免浪费免费额度。
## What：已知约束
- 计费：免费，有档位限制（具体数值以[官方档位说明](https://www.showapi.com/free-api)为准，文档未给数字）。
- 失败判定：返回 `showapi_res_body.ret_code` 非 `"0"`（含限流类失败）；具体限流码文档未枚举，以 `showapi_res_error` 文案定位。
- 无服务端订阅/回调（见[并发架构篇](https://www.showapi.com/guides/image-process-concurrency-1)）。
## How：令牌桶 + 退避 + 缓存
**Python：带限频与重试的封装**
```python
import requests, time, hashlib, os
CACHE = "/tmp/thumb_cache"
os.makedirs(CACHE, exist_ok=True)
def thumb(path, rate="0.6", max_retry=3):
key = hashlib.md5(open(path,"rb").read()).hexdigest() + rate
cp = os.path.join(CACHE, key)
if os.path.exists(cp): # 缓存命中，直接复用
return open(cp).read().strip()
for i in range(max_retry):
r = requests.post("https://route.showapi.com/1-1", params={"appKey":"YOUR_APPKEY"},
data={"type":"rate","rate":rate}, files={"src_img": open(path,"rb")}, timeout=10)
body = r.json()["showapi_res_body"]
if str(body.get("ret_code")) == "0":
url = body["des_pic_url"]
open(cp,"w").write(url); return url
time.sleep(2 ** i) # 指数退避：1s,2s,4s
raise RuntimeError("重试后仍失败: " + r.json().get("showapi_res_error",""))
```
**Node.js：简单节流（令牌桶思路）**
```javascript
let tokens = 5, last = Date.now();
async function acquire() {
const now = Date.now(); tokens = Math.min(5, tokens + (now - last) / 200); last = now;
if (tokens < 1) { await new Promise(r => setTimeout(r, 200)); return acquire(); }
tokens -= 1;
}
```
## 返回示例
```json
{ "showapi_res_body": { "ret_code": "0", "des_pic_url": "http://app1.showapi.com/temp/1.jpg" } }
```
## 进阶/边界
- 限流应以「退避 + 缓存」组合应对，单纯堆重试会加剧限流。
- `des_pic_url` 是临时地址，缓存建议存图片二进制或自有归档地址，而非只存临时链接。
- 文档无具体档位数字，扩容/企业需求以[官方档位说明](https://www.showapi.com/free-api)为准。
## FAQ
**Q1：怎么知道被限流了？** 返回 `ret_code` 非 0 且 `showapi_res_error` 提示频率/额度相关，即疑似限流；具体码文档未枚举。
**Q2：退避间隔多少合适？** 文档未给，示例用 1/2/4 秒指数退避，可结合实际失败文案调。
**Q3：缓存 key 怎么定？** 用「原图哈希 + 参数（如 rate/size）」组合，参数变了算不同结果。
**Q4：能申请更高档位吗？** 以官方档位说明与控制台为准，本文不编造额度数字。
## 相关能力 / 下一步阅读
- [图片水印裁剪缩略接口：高并发图片处理架构（客户端异步+重试）](https://www.showapi.com/guides/image-process-concurrency-1)
- [图片水印裁剪缩略接口返回字段全解：ret_code 与 des_pic_url 一文读懂](https://www.showapi.com/guides/image-process-response-codes-1)
- **本系列共 13 篇**：查看[图片水印裁剪缩略接口指南总目录](https://www.showapi.com/guides/image-process-guides-1)
