HonestQR API v1

以编程方式创建二维码并读取扫描统计。先在控制台（API 密钥区）获取 API key，再作为 Bearer token 传入。

Base URL： https://qr.zalize.com

认证： Authorization: Bearer hqr_…

速率限制： 每个 API key 每分钟 60 次请求（超出返回 HTTP 429）。

渲染静态二维码

GET /api/v1/static —— 直接返回图片。不存储任何内容；静态码永不过期。查询参数：data（必填，最长 2048 字符）、format（默认 png，或 svg）、size（像素，128–4096，默认 1024）。

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/static?data=https%3A%2F%2Fexample.com&format=png&size=1024" \
  -o qr.png

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/static?data=https%3A%2F%2Fexample.com&format=svg" \
  -o qr.svg

创建动态二维码

POST /api/v1/qrcodes —— 创建可编辑的短链（https://qr.zalize.com/r/<slug>）并返回图片 URL。请求体字段：target_url（必填）、name、folder。免费版含 3 个动态码。

curl -X POST https://qr.zalize.com/api/v1/qrcodes \
  -H "Authorization: Bearer $HONESTQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/menu", "name": "Menu"}'

{
  "qrcode": { "id": "…", "slug": "abc1234", "short_url": "https://qr.zalize.com/r/abc1234", … },
  "image_png": "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=png",
  "image_svg": "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=svg"
}

JavaScript 示例

适用于 Node.js 18+ 及任何带 fetch 的运行时（Workers、Deno、Bun；浏览器请经由后端代理——切勿把 key 发到客户端）。

const BASE = 'https://qr.zalize.com';
const headers = {
  Authorization: `Bearer ${process.env.HONESTQR_KEY}`,
  'Content-Type': 'application/json',
};

// Create a dynamic code
const res = await fetch(`${BASE}/api/v1/qrcodes`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ target_url: 'https://example.com/menu', name: 'Menu' }),
});
if (!res.ok) throw new Error(`HonestQR ${res.status}: ${(await res.json()).error}`);
const { qrcode } = await res.json();

// Fetch its stats later
const stats = await (await fetch(`${BASE}/api/v1/qrcodes/${qrcode.id}/stats`, { headers })).json();
console.log(qrcode.short_url, stats.total);

Python 示例

import os, requests

BASE = "https://qr.zalize.com"
HEADERS = {"Authorization": f"Bearer {os.environ['HONESTQR_KEY']}"}

# Render a static QR code (never stored, never expires)
png = requests.get(
    f"{BASE}/api/v1/static",
    params={"data": "https://example.com", "format": "png", "size": 1024},
    headers=HEADERS,
)
png.raise_for_status()
open("qr.png", "wb").write(png.content)

# Create a dynamic code
r = requests.post(
    f"{BASE}/api/v1/qrcodes",
    json={"target_url": "https://example.com/menu", "name": "Menu"},
    headers=HEADERS,
)
r.raise_for_status()
print(r.json()["qrcode"]["short_url"])

下载动态码图片

GET /api/v1/qrcodes/:id/image —— 查询参数 format（png/svg）与 size。

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=svg" -o menu.svg

列出你的二维码

GET /api/v1/qrcodes

curl -H "Authorization: Bearer $HONESTQR_KEY" https://qr.zalize.com/api/v1/qrcodes

扫描统计

GET /api/v1/qrcodes/:id/stats —— 总量及按天（近 30 天）、国家、设备的分布。

curl -H "Authorization: Bearer $HONESTQR_KEY" https://qr.zalize.com/api/v1/qrcodes/<id>/stats

错误

所有错误均为 JSON：{"error": "…"}。

状态码	含义	处理方式
`400`	无效请求（参数缺失/无效）	查看 `error` 信息并修正参数。
`401`	API key 缺失或无效	传入 `Authorization: Bearer hqr_…`；若已吊销，在控制台重新生成。
`402`	达到套餐上限（免费版：3 个动态码）	删除不用的码或升级 Pro。
`404`	二维码不存在（或属于其他账号）	用 `GET /api/v1/qrcodes` 核对 `id`。
`429`	触发限流（每 key 每分钟 60 次）	等一分钟后重试；尽量合并读取。

想要免代码的嵌入方式？

也可以把完整生成器作为免费嵌入 widget放到你自己的网站上——一段代码，无需 API key。

在用 AI 智能体？

HonestQR 还提供免费的 MCP 服务器，让 Claude、Cursor 等 MCP 客户端直接生成与解码二维码——无需 API key。