图片水印裁剪缩略接口实战：网站/App 图库如何接入缩略图生成
# 图片水印裁剪缩略接口实战：网站/App 图库如何接入缩略图生成
> 接口/接入点：图片水印裁剪缩略接口（apiCode=1）· 1-1 生成缩略图 · 是否免费：免费 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：前端、全栈、产品经理 · 阅读时间：7 分钟
## 核心要点
- 原图存原图，缩略图按场景（列表/详情/头像）各生成一份，存 `des_pic_url`。
- 触发时机：上传完成后异步生成，用户端只加载对应尺寸，省流量。
- 免费接口有档位限制，批量场景务必加本地缓存与限流保护（见[频率控制篇](https://www.showapi.com/guides/image-process-ratelimit-1)）。
## Why：图库为什么要缩略图
网站图库若直接展示原图，列表页一次加载十几张几 MB 的图，首屏能卡 10 秒。生成多尺寸缩略图后，列表用 200px、详情用 800px，体验与带宽双优。
## What：接口速览
| 项 | 值 |
|------|------|
| 地址 | `https://route.showapi.com/1-1?appKey=YOUR_APPKEY` |
| 必填 | `type`（size/rate）、`src_img`（File） |
| 可选 | `width`、`height`、`keepRate`、`rate` |
| 返回 | `showapi_res_body.des_pic_url` |
## How：全链路设计
**数据表设计**
```
images(id, origin_url, thumb_200, thumb_800, created_at)
```
**触发流程**：用户上传原图 → 落库 origin_url → 调 1-1 生成 200px 与 800px → 回写 thumb_200/thumb_800。
**Python：一次上传生成两种尺寸**
```python
import requests
def make_thumb(path, size):
url = "https://route.showapi.com/1-1"
data = {"type": "size", "width": str(size), "height": str(size), "keepRate": "1"}
files = {"src_img": open(path, "rb")}
r = requests.post(url, params={"appKey": "YOUR_APPKEY"}, data=data, files=files, timeout=10)
body = r.json()["showapi_res_body"]
if str(body.get("ret_code")) != "0":
raise RuntimeError(body.get("ret_code"))
return body["des_pic_url"]
thumb_200 = make_thumb("demo.jpg", 200)
thumb_800 = make_thumb("demo.jpg", 800)
print(thumb_200, thumb_800)
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1-1?appKey=YOUR_APPKEY" \
-F "type=size" -F "width=200" -F "height=200" -F "keepRate=1" -F "src_img=@demo.jpg"
```
**Node.js（fetch）**
```javascript
import fs from "fs";
async function makeThumb(path, size) {
const form = new FormData();
form.append("type", "size"); form.append("width", String(size));
form.append("height", String(size)); form.append("keepRate", "1");
form.append("src_img", new Blob([fs.readFileSync(path)]), "demo.jpg");
const json = await (await fetch("https://route.showapi.com/1-1?appKey=YOUR_APPKEY", {method:"POST",body:form})).json();
const b = json.showapi_res_body;
if (String(b.ret_code) !== "0") throw new Error(b.ret_code);
return b.des_pic_url;
}
```
## 返回示例
```json
{ "showapi_res_body": { "ret_code": "0", "des_pic_url": "http://app1.showapi.com/temp/1.jpg" } }
```
## 进阶/边界
- `keepRate=1` 保持原比例，只按 `width`/`height` 中较小约束缩放，避免变形。
- 同一原图不要反复调用，生成后落库复用（[频率控制篇](https://www.showapi.com/guides/image-process-ratelimit-1)）。
- 需要水印一并加，看[水印位置篇](https://www.showapi.com/guides/watermark-position-guide-1)与[电商方案](https://www.showapi.com/guides/ecommerce-image-plan-1)。
## FAQ
**Q1：列表和详情用不同尺寸，要调两次吗？** 是，1-1 一次只出一种尺寸；也可仅生成一份中等尺寸前端用 CSS 自适应。
**Q2：keepRate 和固定宽高冲突？** `keepRate=1` 时按原比例，实际输出可能小于设定的宽高，属正常。
**Q3：原图很大怎么办？** 免费接口对体积有档位限制，过大可能失败；先压缩或走 1-8 URL 形态（见[URL 缩略篇](https://www.showapi.com/guides/url-thumbnail-guide-1)）。
**Q4：des_pic_url 是临时的吗？** 以返回地址有效期为准，生产环境请下载归档到自有存储。
## 相关能力 / 下一步阅读
- [图片水印裁剪缩略接口：5 分钟生成第一张缩略图](https://www.showapi.com/guides/image-thumbnail-quickstart-1)
- [图片水印裁剪缩略接口：免费档位限制与频率控制，如何避免触发限流](https://www.showapi.com/guides/image-process-ratelimit-1)
- **本系列共 13 篇**：查看[图片水印裁剪缩略接口指南总目录](https://www.showapi.com/guides/image-process-guides-1)
