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`);
}

---

功能概览

---

模板分类（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 提供商与模型

你的提供商提供的任何模型 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 → OpenAI）。这些调用计入你套餐的托管 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 个专业设计的二维码模板。

查询参数：

响应 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} — 基于模板生成

使用预设计模板生成二维码。模板的视觉设计保持不变；你可以选择性地覆盖输出设置。

路径参数：

请求体：

{
  "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"
}

---

错误处理

所有错误都遵循统一的格式：

{
  "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