分享自用二维码API

常规讨论
1

二维码生成 API 文档

我们支持高效的二维码在线生成服务。你可以通过简单的 HTTP GET 请求生成二维码：

Plaintext

https://api.qiankunol.com/qr?text=Here's my text

请求参数说明

通过在 URL 中配置以下查询参数自定义二维码样式与内容：

参数名称 说明 是否必填 默认值
text 二维码承载内容（可为 URL 或任意文本，必须进行 URL 编码） 是 无
format 导出格式，支持 png、svg 或 base64 否 png
margin 二维码外边距（模块单位） 否 4
size 二维码宽度与高度像素值（正方形） 否 150
dark 二维码深色网格单元的十六进制颜色代码 否 000000（黑色）
light 二维码浅色背景网格的十六进制颜色代码（设为 0000 可实现透明背景） 否 ffffff（白色）
finderColor 三个角定位图案的十六进制颜色，默认同 dark 否 与 dark 相同
dotStyle 数据模块形状：square（方形）、dot（圆形，别名 dots/round/circle）、rounded（圆角） 否 square
finderStyle 定位图案形状：square（方形）、rounded（圆角）、circle（圆形） 否 square
finderDotStyle 定位图案中心点形状：square、rounded、dot 否 跟随 finderStyle
ecLevel 容错级别：L、M、Q、H（级别越高抗遮挡能力越强） 否 M（含中心图时自动为 H）
centerImageUrl 中心 Logo 图片的完整 URL（必须经过 URL 编码） 否 无
centerImageSizeRatio 中心图片占二维码整体的比例，取值范围 0.0 至 1.0 否 0.3
centerImageWidth 中心图片的像素宽度（与 Ratio 二选一） 否 无
centerImageHeight 中心图片的像素高度（与 Ratio 二选一） 否 无
caption 显示在二维码下方的文本标签 否 无
captionFontFamily 底部文本的字体名称 否 'sans-serif'
captionFontSize 底部文本的字体大小（像素） 否 10
captionFontColor 底部文本颜色（颜色英文名称或十六进制代码） 否 black

提示：请务必对 text 参数进行标准 URL 编码（URL Encode），否则包含 &、?、空格等特殊字符时会被错误截断。

个性化定制示例

1. 调整颜色、边距与高容错 SVG

Plaintext

https://api.qiankunol.com/qr?text=Here's%20my%20text&dark=f00&light=0ff&ecLevel=Q&format=svg

2. 样式模块与定位点定制

Plaintext

https://api.qiankunol.com/qr?text=Here's%20my%20text&dotStyle=rounded&finderStyle=circle&finderColor=ff0066

3. 添加中心 Logo 图标

中心图片需存放在公网可访问的地址上（支持 PNG、JPG 或 Base64 Data URI）。建议 Logo 尺寸占比控制在 30% 以内，避免影响扫码识别率：

Plaintext

https://api.qiankunol.com/qr?text=Here's%20my%20text&centerImageUrl=https%3A%2F%2Fcdn-icons-png.flaticon.com%2F512%2F1389%2F1389234.png&centerImageSizeRatio=0.25

4. 底部添加说明文字

Plaintext

https://api.qiankunol.com/qr?text=abc123&caption=Scan%20Me&captionFontFamily=mono&captionFontSize=18

兼容 Google Image Charts 迁移

本 API 兼容 Google Charts 的经典参数（如 cht=qr、chs、chl）。如需迁移旧项目，只需将域名 chart.googleapis.com 替换为 api.qiankunol.com：

Plaintext

https://api.qiankunol.com/chart?cht=qr&chs=150x150&chl=Testing123

常见问题排查：特殊字符与参数丢失

  • 问题现象：扫码后发现 URL 参数不全，或者内容中包含的 &、?、#、= 字符丢失。

  • 产生原因：作为二维码内容的 URL 本身含有查询参数，未编码时与外层的 API 参数发生了冲突解析。

  • 解决方案：将传入 text（或兼容接口的 chl）的内容进行完整 URL 编码。

转换示例：

  • 原始目标网址：[https://example.com/page?param1=value1&param2=value2](https://example.com/page?param1=value1&param2=value2)

  • URL 编码后内容：https%3A%2F%2Fexample.com%2Fpage%3Fparam1%3Dvalue1%26param2%3Dvalue2

  • 最终请求调用：

Plaintext

https://api.qiankunol.com/qr?text=https%3A%2F%2Fexample.com%2Fpage%3Fparam1%3Dvalue1%26param2%3Dvalue2