二维码生成和识别：5 分钟接入，从注册到生成第一个二维码
# 二维码生成和识别：5 分钟接入，从注册到生成第一个二维码
> 接口/接入点：二维码生成和识别（apiCode=887，接入点 887-1 生成）· 是否免费：是（注册默认免费，有档次限制）· 请求方式：POST/GET · 返回格式：JSON · 适用人群：新注册用户、初级开发者 · 阅读时间：约 5 分钟
## 核心要点
- 生成二维码只需一个必填参数 `content`，返回 `imgUrl` 即为图片地址。
- 调用地址 `https://route.showapi.com/887-1?appKey=YOUR_APPKEY`，appKey 放 query。
- 生成图存于 ShowAPI 服务器，**每 12 小时清理**，拿到 `imgUrl` 后请及时下载保存。
## Why：这跟我有什么关系
无论是做活动海报、简历二维码、点餐码还是支付码，第一步都是"把一段文字/链接变成一张二维码图片"。本接口免费、无需自建二维码库，注册即有额度，适合快速验证想法或中小流量业务。
## What：前置条件与接口速览
| 项 | 说明 |
|----|------|
| 接口地址 | `https://route.showapi.com/887-1?appKey=YOUR_APPKEY` |
| 接入点 | 887-1 二维码生成 |
| 请求方式 | POST / GET |
| 鉴权 | query 参数 `appKey` |
| 必填参数 | `content`（要生成二维码的内容） |
| 可选参数 | `size`（图片大小 1-10 及 16/20/30）、`imgExtName`（jpeg/jpg/png/gif） |
| 返回关键字段 | `ret_code`（0 成功）、`flag`、`msg`、`imgUrl` |
| 计费 | 免费，注册默认可调用，有使用档次限制 |
获取 AppKey：登录 ShowAPI 控制台 → [我的 AppKey](https://www.showapi.com/console#/myApp)，替换下方 `YOUR_APPKEY`。
## How：三步拿到第一张二维码
### 1. Python（requests）
```python
import requests
url = "https://route.showapi.com/887-1"
resp = requests.post(
url,
params={"appKey": "YOUR_APPKEY"}, # appKey 放 query
data={
"content": "https://www.showapi.com", # 必填：二维码内容
"size": "8", # 可选：1-10，content 极少时用 16/20/30
"imgExtName": "jpg", # 可选：jpeg/jpg/png/gif
},
timeout=10,
)
body = resp.json()["showapi_res_body"]
if body.get("ret_code") == "0":
print("二维码地址:", body["imgUrl"])
# ⚠️ 生成图每 12h 清理，建议立即下载保存
else:
print("生成失败:", body.get("msg"))
```
### 2. cURL
```bash
curl -X POST "https://route.showapi.com/887-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "content=https%3A%2F%2Fwww.showapi.com&size=8&imgExtName=jpg"
```
### 3. Node.js（fetch）
```javascript
const resp = await fetch("https://route.showapi.com/887-1?appKey=YOUR_APPKEY", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
content: "https://www.showapi.com",
size: "8",
imgExtName: "jpg",
}),
});
const body = (await resp.json()).showapi_res_body;
if (body.ret_code === "0") console.log("二维码地址:", body.imgUrl);
else console.log("生成失败:", body.msg);
```
## 返回示例与解析
```json
{
"showapi_res_code": 0,
"showapi_res_error": "",
"showapi_res_id": "ce135f6739294c63be0c021b76b6fbff",
"showapi_res_body": {
"ret_code": "0",
"flag": "ture",
"msg": "操作成功!",
"imgUrl": "http://app2.showapi.com/img/qrCode/201601/1451885183552.jpg"
}
}
```
字段说明（详见[返回字段全解](https://www.showapi.com/guides/qrcode-response-fields-887)）：
- `ret_code`：业务是否成功，`"0"` 为成功（**统一以它判成功**）。
- `flag`：生成是否成功；注意本接入点示例值为 `ture`（疑似拼写），不要依赖字面判等，详见[错误码与失败排查](https://www.showapi.com/guides/qrcode-error-handling-887)。
- `imgUrl`：二维码图片地址，拿到后请及时下载（12h 清理）。
## 进阶 / 边界
- **内容不宜过长**：`content` 越长，二维码越密、尺寸越大；长内容建议 size < 5。
- **格式选择**：`imgExtName` 支持 jpeg/jpg/png/gif，默认 jpg。
- **保存时效**：图片存 ShowAPI 服务器，每 12 小时删除，生产环境务必落盘到自有存储，方案见[保存与缓存策略](https://www.showapi.com/guides/qrcode-save-strategy-887)。
## FAQ
**Q1：免费吗？需要付费吗？**
A：注册后默认可免费调用，设有使用档次限制防止滥用；更高档位可用平台积分兑换。具体档位以[官方档位说明](https://www.showapi.com/free-api)为准。
**Q2：生成的二维码能用多久？**
A：图片存于 ShowAPI 服务器，每 12 小时清理一次。建议生成后立即下载到自有存储或 CDN。
**Q3：appKey 放哪？**
A：放 query 参数 `?appKey=YOUR_APPKEY`，不要写死在客户端代码里暴露给前端。
**Q4：只传 content 可以吗？**
A：可以。`size` 与 `imgExtName` 均为可选，默认 size=8、jpg 格式。
**Q5：返回 flag 是 "ture" 是不是出错了？**
A：不是。生成接入点返回示例确为 `ture`（疑似拼写），成功仍以 `ret_code=="0"` 判断即可。
## 相关能力 / 下一步阅读
- [二维码生成和识别：返回字段全解（ret_code / flag / imgUrl / retText）](https://www.showapi.com/guides/qrcode-response-fields-887)
- [二维码生成和识别：三种识别方式怎么选（上传 / 图片地址 / Base64）](https://www.showapi.com/guides/qrcode-recognition-compare-887)
- [二维码生成和识别：图片每 12 小时清理，如何设计保存与缓存策略](https://www.showapi.com/guides/qrcode-save-strategy-887)
- **本系列共 12 篇**：查看[二维码生成和识别指南总目录](https://www.showapi.com/guides/qrcode-guides-887)
