QR Branding API
可定制程度最高的二维码 API。 使用 37 种模块形状、118 个模板、AI 驱动的设计和 5 种输出格式,生成令人惊艳、带品牌风格且符合 ISO 18004 的二维码。
在 RapidAPI 上订阅:rapidapi.com/quartzondev/api/qr-branding。套餐与配额请见 RapidAPI 页面。
快速开始
1. 生成自定义二维码
curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/generate" \
-H "Content-Type: application/json" \
-H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
-H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
-d '{
"content": "https://example.com",
"primaryColor": "#1a1a2e",
"backgroundColor": "#FFFFFF",
"moduleShape": "circle",
"fileFormat": "png",
"outputWidth": 512,
"eccLevel": "H"
}'
响应:
{
"success": true,
"qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
"format": "png",
"contentType": "image/png",
"sizeBytes": 15234
}
2. 基于模板生成
curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/templates/cyber-neon" \
-H "Content-Type: application/json" \
-H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
-H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
-d '{
"content": "https://mywebsite.com",
"outputWidth": 600
}'
3. AI 驱动的二维码
curl -X POST "https://qr-branding.p.rapidapi.com/api/qr/ai/generate" \
-H "Content-Type: application/json" \
-H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
-H "X-RapidAPI-Host: qr-branding.p.rapidapi.com" \
-d '{
"prompt": "A luxurious gold and black QR code with rounded modules and a subtle glow effect, suitable for a premium brand",
"content": "https://premium-brand.com",
"llmProvider": "openai",
"llmApiKey": "sk-your-openai-key",
"creativity": 0.7,
"strictScannability": true,
"stylePreset": "luxury"
}'
响应:
{
"success": true,
"qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
"format": "png",
"contentType": "image/png",
"sizeBytes": 28456,
"generatedConfig": { },
"aiExplanation": "I designed a premium QR code with...",
"llmProviderUsed": "openai",
"llmModelUsed": "gpt-6-luna"
}
代码示例
Python
import requests
url = "https://qr-branding.p.rapidapi.com/api/qr/generate"
headers = {
"Content-Type": "application/json",
"X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
"X-RapidAPI-Host": "qr-branding.p.rapidapi.com"
}
payload = {
"content": "https://example.com",
"primaryColor": "#FF6B35",
"moduleShape": "star",
"eccLevel": "H",
"outputWidth": 800,
"fileFormat": "png"
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
if data["success"]:
import base64
img_bytes = base64.b64decode(data["qrBase64"])
with open("my_qr.png", "wb") as f:
f.write(img_bytes)
print(f"QR saved! Size: {data['sizeBytes']} bytes")
JavaScript(Node.js)
const response = await fetch(
"https://qr-branding.p.rapidapi.com/api/qr/generate",
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-RapidAPI-Key": "YOUR_RAPIDAPI_KEY",
"X-RapidAPI-Host": "qr-branding.p.rapidapi.com",
},
body: JSON.stringify({
content: "https://example.com",
primaryColor: "#0066FF",
moduleShape: "hexagon",
eccLevel: "H",
outputWidth: 600,
fileFormat: "png",
}),
}
);
const data = await response.json();
if (data.success) {
const buffer = Buffer.from(data.qrBase64, "base64");
require("fs").writeFileSync("qr_code.png", buffer);
console.log(`QR generated: ${data.sizeBytes} bytes`);
}
功能概览
| 类别 | 详情 |
|---|---|
| 模块形状 | 37 种:square、circle、diamond、star、heart、hexagon、leaf、cross、dot、mosaic、clipped、edgecut、pointed、pill、rounded、japanese、octagon、shield、arrow、drop + 自定义 SVG |
| 模板 | 118 个预设计模板,涵盖 28 个分类 |
| AI 提供商 | 9 个 LLM 提供商,外加任何与 OpenAI 兼容的端点(自带密钥),或无需密钥的托管 AI |
| 输出格式 | PNG、JPEG、SVG、PDF、WebP |
| 最大分辨率 | 4,096 × 4,096 像素 |
| 渐变 | 线性、径向、扫描渐变,色标数量不限 |
| 视觉效果 | 阴影、发光/霓虹、浮雕/3D、噪点、模糊、边缘渐隐、颜色滤镜 |
| Logo 支持 | URL 或 Base64,圆形/方形/圆角形状,阴影,自定义尺寸 |
| 文字叠加 | 环形文字、中心条带、CTA 横幅 |
| 边框 | 矩形、对话气泡、徽章、盾牌、圆形 |
| 纠错 | L (7%)、M (15%)、Q (25%)、H (30%) — ISO 18004 |
| 内容辅助 | WiFi、vCard、地理位置字符串生成器 |
| 背景图片 | URL/Base64、混合模式、适配模式、模糊 |
| 连接模块 | fluid、sharp、round 连接,适合艺术化设计 |
模板分类(28 个)
Technology、Corporate、Social、Luxury、Nature、Artistic、Marketing、Events、Music、Fun、Background、Culture、Industry、Restaurant、Retail、Education、Travel、Automotive、Healthcare、Social Media、Art & Design、Business、Food & Drink、Finance、Health、Legal、Non-Profit、Real Estate。
使用 GET /api/qr/templates?category=luxury 按分类筛选。
AI 提供商与模型
| 提供商 | 模型 |
|---|---|
| OpenAI | gpt-6-astra, gpt-6.1-sol, gpt-6-luna, gpt-6-sol, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-4.1-mini |
| Anthropic | claude-fable-5-1, claude-opus-5-5, claude-sonnet-5-5, claude-haiku-4-5 |
| gemini-3.1-pro-preview, gemini-3.8-flash, gemini-3.5-flash-lite, gemini-3.5-flash | |
| Mistral | mistral-large-latest, mistral-medium-latest, mistral-small-latest |
| Cohere | command-a-plus-05-2026, command-a-03-2025, command-a-reasoning-08-2025, command-r7b-12-2024 |
| Groq | openai/gpt-oss-120b, openai/gpt-oss-20b, llama-3.3-70b-versatile |
| xAI | grok-4.7, grok-4.3, grok-4.20-0309-non-reasoning |
| DeepSeek | deepseek-v4-pro, deepseek-flash |
| Qwen | qwen3.8-max, qwen3.7-plus, qwen3.8-flash |
| Local | 任何与 OpenAI 兼容的端点(Ollama、LM Studio、vLLM);设置 llmProvider: "local" 并传入 localEndpoint |
你的提供商提供的任何模型 ID 都可以使用;此列表列出的是推荐模型。
注意: 使用
/api/qr/ai/generate时,你需要为所选的 LLM 提供商提供自己的 API 密钥,费用由提供商直接向你计费,QR Branding 不加收任何费用。使用/api/qr/ai/generate-managed时无需 LLM 密钥:模型由我们运行,这些调用计入你套餐中独立的托管 AI 配额。
端点
POST /api/qr/generate — 生成自定义二维码
生成一个完全可定制的二维码,提供 100 多个参数,包括模块形状、渐变、效果、logo、文字叠加、边框等。支持 JSON 请求体,或使用 multipart/form-data 上传 logo 文件。
请求体:
{
"content": "https://example.com",
"eccLevel": "H",
"pixelsPerModule": 20,
"outputWidth": 512,
"fileFormat": "png",
"quality": 90,
"responseType": "base64",
"backgroundColor": "#FFFFFF",
"transparentBackground": false,
"primaryColor": "#000000",
"secondaryColor": null,
"foregroundStyle": "solid",
"gradientType": "linear",
"gradientDirection": "vertical",
"gradientColors": ["#FF0000", "#0000FF"],
"gradientStops": [0.0, 1.0],
"gradientAngle": 0,
"qrShape": "square",
"moduleShape": "square",
"moduleScale": 0.85,
"moduleRotation": 0,
"moduleStyle": "solid",
"modulePattern": "standard",
"connectedStyle": "none",
"finderOuterShape": "square",
"finderInnerShape": "square",
"finderOuterColor": "#000000",
"finderInnerColor": "#000000",
"finderStyle": "standard",
"logoUrl": "https://example.com/logo.png",
"logoShape": "circle",
"logoSizePercent": 18,
"logoBorderWidth": 2,
"logoBorderColor": "#FFFFFF",
"logoShadow": true,
"logoBackground": "solid",
"ctaText": "SCAN ME"
}
响应 200:
{
"success": true,
"qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
"format": "png",
"contentType": "image/png",
"sizeBytes": 15234
}
响应 400:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed with 1 error.",
"details": [
{
"field": "moduleShape",
"code": "INVALID_MODULE_SHAPE",
"message": "Invalid module shape 'triangle'. Valid shapes: square, circle, diamond, star, heart, hexagon, leaf, cross, dot, mosaic, clipped, edgecut, pointed, pill, rounded, japanese, octagon, shield, arrow, drop."
}
]
}
}
POST /api/qr/ai/generate — 用 AI 生成二维码
用自然语言描述你理想中的二维码,让 AI 为你设计。支持 9 个 LLM 提供商以及任何与 OpenAI 兼容的端点(local),并接受提供商提供的任意模型 ID。此端点需要你提供自己的 LLM API 密钥;如果不想使用密钥,请使用 POST /api/qr/ai/generate-managed(见下文)。
请求体:
{
"prompt": "A modern tech-style QR code with hexagonal modules, a blue-to-purple gradient, subtle glow effect, and rounded finder patterns",
"content": "https://myapp.com",
"llmProvider": "openai",
"llmApiKey": "sk-your-api-key-here",
"llmModel": "gpt-6-luna",
"creativity": 0.7,
"strictScannability": true,
"stylePreset": "tech",
"fileFormat": "png",
"outputWidth": 800,
"logoUrl": "https://example.com/logo.png",
"ctaText": "Download App"
}
响应 200:
{
"success": true,
"qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
"format": "png",
"contentType": "image/png",
"sizeBytes": 28456,
"generatedConfig": {
"content": "https://myapp.com",
"moduleShape": "hexagon",
"primaryColor": "#4A90D9",
"gradientColors": ["#4A90D9", "#7B2FF7"],
"gradientType": "linear",
"gradientDirection": "vertical",
"finderOuterShape": "roundedsquare",
"finderInnerShape": "circle",
"eccLevel": "H"
},
"aiExplanation": "I designed a tech-inspired QR code with hexagonal modules...",
"llmProviderUsed": "openai",
"llmModelUsed": "gpt-6-luna"
}
POST /api/qr/ai/generate-managed — 托管 AI(无需 LLM 密钥)
请求格式与 /api/qr/ai/generate 相同,但 llmProvider、llmApiKey 和 llmModel 会被忽略:无需 LLM 密钥。引擎使用自有模型,并带有回退链(Groq → Gemini)。这些调用计入你套餐的托管 AI 配额。
{
"prompt": "A luxurious gold and black QR with rounded modules and a subtle glow effect",
"content": "https://premium-brand.com",
"creativity": 0.7,
"strictScannability": true,
"stylePreset": "luxury",
"fileFormat": "png",
"outputWidth": 800
}
响应格式与 /api/qr/ai/generate 相同,另外多一个 "managed": true 字段。
GET /api/qr/ai/providers — 获取 AI 提供商
列出所有支持 AI 二维码生成的 LLM 提供商及其可用模型。
响应 200:
{
"success": true,
"count": 10,
"providers": [
{
"id": "openai",
"name": "OpenAI",
"defaultModel": "gpt-6-luna",
"availableModels": ["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna", "gpt-6-sol", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-4.1-mini"]
},
{
"id": "anthropic",
"name": "Anthropic",
"defaultModel": "claude-sonnet-5-5",
"availableModels": ["claude-fable-5-1", "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-4-5"]
}
]
}
GET /api/qr/templates — 列出模板
浏览 28 个分类下 118 个专业设计的二维码模板。
查询参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
category | string | 否 | 按分类筛选(例如 luxury、corporate、social) |
响应 200:
{
"success": true,
"count": 118,
"categories": [
"Technology", "Corporate", "Social", "Luxury", "Nature",
"Artistic", "Marketing", "Events", "Music", "Fun"
],
"templates": [
{
"id": "cyber-neon",
"name": "Cyber Neon",
"category": "Technology",
"description": "Futuristic glowing neon style with diamond modules and vibrant cyan-pink gradient"
},
{
"id": "professional-blue",
"name": "Professional Blue",
"category": "Corporate",
"description": "Clean corporate style with blue gradient, ideal for business"
}
]
}
POST /api/qr/templates/{templateId} — 基于模板生成
使用预设计模板生成二维码。模板的视觉设计保持不变;你可以选择性地覆盖输出设置。
路径参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
templateId | string | 是 | 来自“列出模板”端点的模板 ID(例如 cyber-neon) |
请求体:
{
"content": "https://mywebsite.com",
"fileFormat": "png",
"responseType": "base64",
"outputWidth": 600,
"logoUrl": "https://example.com/logo.png",
"ctaText": "Visit Us"
}
响应 200:
{
"success": true,
"qrBase64": "iVBORw0KGgoAAAANSUhEUg...",
"format": "png",
"contentType": "image/png",
"sizeBytes": 22100
}
POST /api/qr/content/wifi — 生成 WiFi 字符串
生成用于二维码编码的 WiFi 连接字符串。扫描二维码的用户会自动收到连接该网络的提示。
请求体:
{
"ssid": "MyNetwork",
"password": "MyP@ssw0rd!",
"encryption": "WPA",
"hidden": false
}
响应 200:
{
"success": true,
"text": "WIFI:T:WPA;S:MyNetwork;P:MyP@ssw0rd!;H:false;;"
}
POST /api/qr/content/vcard — 生成 vCard 字符串
生成用于二维码编码的 vCard 联系人字符串。扫描后,二维码会提示用户将联系人保存到手机。
请求体:
{
"firstName": "John",
"lastName": "Doe",
"phone": "+1-555-123-4567",
"email": "john.doe@example.com",
"org": "Acme Corp",
"url": "https://johndoe.com"
}
响应 200:
{
"success": true,
"text": "BEGIN:VCARD\nVERSION:3.0\nN:Doe;John\nFN:John Doe\nTEL:+1-555-123-4567\nEMAIL:john.doe@example.com\nORG:Acme Corp\nURL:https://johndoe.com\nEND:VCARD"
}
POST /api/qr/content/geo — 生成地理位置字符串
生成用于二维码编码的地理位置 URI。扫描后,二维码会在用户默认的地图应用中打开该位置。
请求体:
{
"lat": 40.7128,
"lng": -74.0060
}
响应 200:
{
"success": true,
"text": "geo:40.7128,-74.006"
}
POST /api/qr/scan-check — 检查设计是否可扫描
在把设计送去印刷之前,先模拟印刷后的代码会被如何读取。发送与 /api/qr/generate 相同的 QrConfig(只有 content 是必填项),引擎会按该设计原样渲染,并在 13 种模拟条件下解码(baseline、small-print、far-away、slight-blur、strong-blur、dim-light、low-contrast、uneven-light、glare、noise、rotated、angle-30、angle-40)。这是模拟,不是保证:它报告的是渲染结果在这些条件下能否被读回,而不是任何手机都一定能扫描。输出设置(fileFormat、responseType、outputWidth、outputHeight、pixelsPerModule)会被忽略,因为检查会自行渲染 PNG。
请求体:
{
"content": "https://example.com/menu",
"eccLevel": "H",
"primaryColor": "#1a1a2e",
"backgroundColor": "#FFFFFF",
"moduleShape": "circle",
"finderOuterShape": "roundedsquare"
}
响应 200:
{
"success": true,
"grade": "good",
"symbolModules": 33,
"version": 4,
"smallestModulePx": 1.5,
"conditions": [
{ "id": "baseline", "core": true, "passed": true, "adaptiveReader": true, "globalReader": true },
{ "id": "small-print", "core": true, "passed": true, "adaptiveReader": true, "globalReader": true },
{ "id": "glare", "core": false, "passed": true, "adaptiveReader": true, "globalReader": false },
{ "id": "angle-40", "core": false, "passed": false, "adaptiveReader": false, "globalReader": false }
],
"sizes": [
{ "id": "table", "distanceCm": 40, "minSideMm": 55 },
{ "id": "wall", "distanceCm": 150, "minSideMm": 200 },
{ "id": "street", "distanceCm": 400, "minSideMm": 530 }
],
"designScore": 96,
"designWarnings": [],
"elapsedMs": 812
}
grade 为 excellent、good、fair 或 poor。每个条件包含 passed、core(获得 good 评级所必需)以及引擎的两个解码器中哪一个读到了它(adaptiveReader、globalReader;两者合起来就是读取器数量,0–2)。sizes 给出在桌面(40 cm)、墙面(1.5 m)和街道(4 m)距离下读取所需的最小印刷边长(毫米);如果该设计在任何测试分辨率下都无法读回,minSideMm 为 null。designScore 是引擎的静态 ISO 18004 设计评分(0–100),designWarnings 列出这些规则标记的 QrConfig 字段。
错误: 400 验证错误(VALIDATION_ERROR、INVALID_JSON、MISSING_REQUIRED_FIELD)· 401 UNAUTHORIZED · 500 QR_GENERATION_FAILED。
GET /api/qr/templates/{templateId}/config — 读取模板的设计
无需渲染二维码即可读取模板的设计。config 是模板完整的 QrConfig:取出任意字段,配上你自己的 content,发送到 /api/qr/generate,就能渲染出调整后的版本。
路径参数:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
templateId | string | 是 | 从模板列表端点获取的模板 ID(例如 cyber-neon) |
响应 200:
{
"success": true,
"id": "cyber-neon",
"name": "Cyber Neon",
"category": "Technology",
"description": "Futuristic glowing neon style with diamond modules and vibrant cyan-pink gradient",
"config": {
"eccLevel": "H",
"primaryColor": "#00f2ea",
"secondaryColor": "#FF7AA4",
"backgroundColor": "#0a0a12",
"foregroundStyle": "linearGradient",
"gradientDirection": "diagonal",
"moduleShape": "diamond",
"finderOuterShape": "roundedsquare",
"finderInnerShape": "diamond",
"logoSizePercent": 22
}
}
错误: id 不存在时返回 404 TEMPLATE_NOT_FOUND。
POST /api/qr/poster — 生成可打印的海报
把一个二维码设计做成可直接打印的海报:A4、A5、A6(纵向)或 US Letter,可选标题、提示语和页脚,并支持设计中的 logo、3 mm 出血和裁切标记。qr 接受与 /api/qr/generate 完全相同的请求体(其 fileFormat 和 responseType 在这里被忽略,文件类型由海报决定)。PDF 为矢量格式,并保留与 /api/qr/generate 相同的扫描保证;PNG 用于预览。
请求体:
{
"qr": {
"content": "https://example.com/menu",
"eccLevel": "H",
"primaryColor": "#1a1a2e",
"backgroundColor": "#FFFFFF",
"moduleShape": "circle"
},
"poster": {
"format": "a4",
"layout": "band",
"headline": "Scan the menu",
"instruction": "Point your camera at the code",
"footer": "example.com",
"showLogo": true,
"bleed": true,
"cropMarks": true,
"fileFormat": "pdf",
"responseType": "base64"
}
}
海报选项:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
format | string | a4 | 成品尺寸:a4、a5、a6(纵向)或 letter(US Letter,纵向) |
layout | string | minimal | minimal、band(强调色页眉色带)、card(带边框卡片)或 tent(折叠式桌面立牌) |
headline | string | — | 二维码上方的大标题 |
instruction | string | — | 二维码下方的短提示语(例如“将摄像头对准二维码”) |
footer | string | — | 底部小字,例如网站或短链接 |
showLogo | boolean | true | 在海报顶部绘制设计中的 logo |
bleed | boolean | false | 在成品尺寸外增加 3 mm 出血,背景和色带会延伸至出血区 |
cropMarks | boolean | false | 在成品尺寸外绘制裁切标记 |
accentColor | string | CTA 或模块颜色 | 标题、色带和卡片边框的品牌色;默认使用 CTA 边框颜色,否则使用模块颜色 |
fileFormat | string | pdf | pdf(矢量,印刷)或 png(位图,预览) |
dpi | integer | 150 | PNG 海报的分辨率,36–300 dpi(PDF 忽略此项) |
responseType | string | base64 | base64(JSON,与 /api/qr/generate 相同)或 binary(文件本身) |
响应 200:
{
"success": true,
"qrBase64": "JVBERi0xLjQKJcfsj6IK...",
"format": "pdf",
"contentType": "application/pdf",
"sizeBytes": 184320
}
当 "responseType": "binary" 时,响应就是文件本身(application/pdf 或 image/png)。
错误: 400 验证错误 · 401 UNAUTHORIZED · 422 QR_UNSCANNABLE(代码无法被读回)· 422 OUTPUT_TOO_COMPLEX(PDF 将超过 20 MB)· 500 QR_GENERATION_FAILED。
GET /api/ping — 健康检查
检查 API 是否可达,不消耗生成配额。
响应 200:
{
"status": "ok"
}
错误: 超过每 IP 探测速率限制(每分钟 10 次)时返回 429。
错误处理
所有错误都遵循统一的格式:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed with 2 errors.",
"details": [
{
"field": "primaryColor",
"code": "INVALID_COLOR_FORMAT",
"message": "Invalid color format. Use hex (#RRGGBB or #RRGGBBAA).",
"value": "not-a-color"
}
]
}
}
错误代码
验证(400)
VALIDATION_ERROR · INVALID_JSON · MISSING_REQUIRED_FIELD · INVALID_FIELD_VALUE · INVALID_COLOR_FORMAT · INVALID_FILE_FORMAT · CONTENT_TOO_LONG · FILE_TOO_LARGE · INVALID_URL · INVALID_ECC_LEVEL · INVALID_MODULE_SHAPE · INVALID_GRADIENT_TYPE · INVALID_RESPONSE_TYPE · VALUE_OUT_OF_RANGE · MULTIPART_CONFIG_MISSING
认证(401)
UNAUTHORIZED · INVALID_API_KEY · MISSING_API_KEY
未找到(404)
RESOURCE_NOT_FOUND · TEMPLATE_NOT_FOUND
AI/LLM 错误(400/500)
INVALID_LLM_PROVIDER · INVALID_LLM_MODEL · LLM_API_KEY_INVALID · AI_GENERATION_FAILED · AI_CONFIG_INVALID · AI_REQUEST_TIMEOUT
输出上限(422)
OUTPUT_TOO_COMPLEX — 该设计会生成超过 20 MB 的 SVG 或 PDF,或每边超过 5120 px 的画布。请导出为 PNG、缩短内容或使用更简单的模块形状
容量(503)
SERVER_BUSY · AI_QUOTA_EXCEEDED (托管 AI 在所有提供商处的配额均已用尽;请稍后再试)
服务器错误(500)
INTERNAL_ERROR · QR_GENERATION_FAILED · LOGO_LOAD_FAILED · BACKGROUND_LOAD_FAILED