图片水印裁剪缩略接口返回字段全解：ret_code 与 des_pic_url 一文读懂
# 图片水印裁剪缩略接口返回字段全解：ret_code 与 des_pic_url 一文读懂
> 接口/接入点：图片水印裁剪缩略接口（apiCode=1）· 全部接入点通用 · 是否免费：免费 · 请求方式：POST/GET · 返回格式：JSON · 适用人群：所有调用者 · 阅读时间：4 分钟
## 核心要点
- 返回是「两层包裹」：系统级字段在外层，业务数据都在 `showapi_res_body` 里。
- 业务成功看 `showapi_res_body.ret_code == "0"`；`des_pic_url` 是生成后的图片地址。
- 系统级 `showapi_res_code` / `showapi_res_error` / `showapi_res_id` 用于排查网关层问题。
## Why：为什么必须读懂返回
调用图片接口，最怕两件事：一是拿到一串 JSON 不知道图片在哪；二是失败时不晓得错在哪。本文把返回结构讲透，后续每篇文章的「返回示例」都链回这里。
## What：返回结构速览
| 层级 | 字段 | 类型 | 说明 |
|------|------|------|------|
| 系统级（外层） | `showapi_res_code` | Number | 网关状态码，0 一般表示网关层正常 |
| 系统级 | `showapi_res_error` | String | 网关层错误信息，成功为空 |
| 系统级 | `showapi_res_id` | String | 本次请求唯一 ID，排查问题用 |
| 业务体 | `showapi_res_body` | Object | 业务数据包裹层 |
| 业务体.内 | `ret_code` | String | 业务结果：**"0" 成功，其他失败** |
| 业务体.内 | `des_pic_url` | String | 处理后图片地址 |
## How：判断成功与取图
**Python（requests）**
```python
import requests
url = "https://route.showapi.com/1-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"type": "rate", "rate": "0.6"}
files = {"src_img": open("demo.jpg", "rb")}
r = requests.post(url, params=params, data=data, files=files, timeout=10)
outer = r.json()
body = outer["showapi_res_body"]
if str(body.get("ret_code")) == "0":
print("成功，图片:", body["des_pic_url"])
else:
print("业务失败 ret_code=", body.get("ret_code"), "err=", outer.get("showapi_res_error"))
```
**cURL**
```bash
curl -X POST "https://route.showapi.com/1-1?appKey=YOUR_APPKEY" \
-F "type=rate" -F "rate=0.6" -F "src_img=@demo.jpg"
```
**Node.js（fetch）**
```javascript
import fs from "fs";
const url = "https://route.showapi.com/1-1?appKey=YOUR_APPKEY";
const form = new FormData();
form.append("type", "rate"); form.append("rate", "0.6");
form.append("src_img", new Blob([fs.readFileSync("demo.jpg")]), "demo.jpg");
const json = await (await fetch(url, { method: "POST", body: form })).json();
const b = json.showapi_res_body;
if (String(b.ret_code) === "0") console.log("图片:", b.des_pic_url);
else console.log("失败", b.ret_code, json.showapi_res_error);
```
## 返回示例
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"des_pic_url": "http://app1.showapi.com/temp/1.jpg"
}
}
```
## 进阶/边界
- `ret_code` 文档只定义了 `0`=成功、其他=失败；**具体非零错误码文档未给枚举**，失败排查优先看 `showapi_res_error` 文案与 `showapi_res_id`。
- 所有 6 个接入点返回结构一致，`des_pic_url` 均为单个地址字符串（非数组）。
- 免费接口有档位限制，超限可能返回非 0，结合[频率控制篇](https://www.showapi.com/guides/image-process-ratelimit-1)处理。
## FAQ
**Q1：`ret_code` 是字符串还是数字？** 文档示例为字符串 `"0"`，判断时统一转字符串比较最稳。
**Q2：返回里没有 `ret_code`？** 以「返回体」schema 为准，它属于 `showapi_res_body`；个别接入点示例只列了 `des_pic_url`，但 schema 含 `ret_code`。
**Q3：`showapi_res_code` 和 `ret_code` 啥区别？** 前者是网关层（请求是否到达/鉴权是否通过），后者是业务层（图片是否处理好）。都看。
**Q4：图片地址打不开？** 可能是临时地址过期或原图超限；生产环境请自行下载归档。
## 相关能力 / 下一步阅读
- [图片水印裁剪缩略接口：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)
