开放 API 文档

接入说明

Base URL：/api/v1。所有接口使用 POST，请求与响应均为 JSON（解码接口也支持 multipart）。

先在控制台 → API 密钥创建一个密钥。密钥只在创建时完整显示一次，请立即保存。

# 最简单的调用
curl -X POST /api/v1/qr \
  -H "X-API-Key: qk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content":"https://example.com"}'

鉴权方式

在请求头带上 X-API-Key: 你的密钥。也支持查询参数 ?apikey=（不推荐，容易泄露在日志里）。

请求头	说明
X-API-Key 必填	控制台创建的密钥，`qk_` 开头
Content-Type	`application/json` 或 `multipart/form-data`

生成二维码

POST/api/v1/qr返回 base64 图片

参数	类型	说明
content 必填	string	二维码内容，最多 2000 字符
format	string	`png`（默认）或 `svg`
size	number	图片边长像素，200–2048，默认 512
ecLevel	string	容错级别 `L / M / Q / H`，默认 M；加 logo 建议 H
moduleStyle	string	点阵样式：square / rounded / dot / dot-sm / classy / diamond / star
fg / bg	string	前景/背景色，十六进制
eyeFrame / eyeBall	string	定位角外框/内点：square / rounded / circle / leaf / dot
gradient	object	`{ enabled, type, from, to, angle }`
logo	object	`{ dataUrl, size, pad, round }`，dataUrl 为 base64 图片
quiet	number	四周留白模块数，0–12，默认 2
caption	string	底部文字，最多 40 字符

// 响应
{
  "ok": true,
  "format": "png",
  "size": 800,
  "image": "data:image/png;base64,iVBORw0KG..."
}

解码

POST/api/v1/decode上传图片或 base64

支持两种方式：multipart/form-data 上传字段 image；或 JSON 传 {"image": "data:image/png;base64,..."}。

# multipart 方式
curl -X POST /api/v1/decode \
  -H "X-API-Key: qk_your_key" \
  -F "image=@qr.png"

// 响应
{ "ok": true, "content": "https://example.com", "type": "url", "version": 4 }

名片码

POST/api/v1/vcard返回 vCard 文本 + 二维码

参数	类型	说明
name	string	姓名（与 phone 至少填一个）
phone	string	手机号
company / title	string	公司 / 职位
email / website	string	邮箱 / 网址
address / note	string	地址 / 备注

// 响应
{ "ok": true, "type": "vcard", "vcard": "BEGIN:VCARD...", "qr": "data:image/png;base64,..." }

查询额度

GET/api/v1/me当前密钥与配额

curl /api/v1/me -H "X-API-Key: qk_your_key"

{ "ok": true, "quota": { "daily": 200, "usedToday": 17 } }

样式参数速查

点阵 moduleStyle	效果	适合
square	标准方块	印刷、远距离扫描
rounded	圆角方块	通用
dot / dot-sm	圆点 / 细点	海报、社交媒体
classy	花瓣形	品牌视觉
diamond / star	菱形 / 星形	活动物料

美化会降低容错余量。加 logo 时请把 ecLevel 设为 H，并保证留白 quiet ≥ 2。

错误码

HTTP	code	含义
400	—	参数错误，响应里的 `error` 会说明原因
401	MISSING_KEY	没有提供 X-API-Key
401	INVALID_KEY	密钥不存在或格式错误
403	KEY_DISABLED	密钥已被停用
403	USER_DISABLED	账号被管理员禁用
429	QUOTA_EXCEEDED	今日配额用完，次日 0 点重置
429	—	触发每分钟限流，参考 `Retry-After`

配额与限流

每日配额由管理员为每个账号设置（默认 200 次/天），按密钥统计调用次数。同时存在每分钟限流（默认 60 次/分钟，可在后台调整）。

若需要更高配额，可在后台「用户管理」调整该账号的每日额度，或联系我们升级方案。

开放 API v1