跳到正文

API 概览

引擎以一个小型 HTTP API 的形式发布。认证方式有两种。

两个渠道

1. RapidAPI Marketplace（现有客户）

使用你的 RapidAPI 代理密钥调用 https://api.qr-branding.com。AI 端点使用你自己的 LLM 密钥，也可使用无需密钥的托管端点。与原来的 Signet QR API 用法完全一致。

2. 消费者额度包（新）

在 /pricing 购买额度包。你的 AI 端点使用服务器端 LLM 密钥（Groq / Gemini / OpenAI），每次生成成功扣除相应额度。前端编辑器以透明方式使用这一渠道。

端点

方法路径用途
POST/api/qr/generate根据显式的 QrConfig 渲染二维码。
POST/api/qr/ai/generate市场 AI：自带 LLM 密钥。
POST/api/qr/ai/generate-managed市场托管 AI：无需 LLM 密钥。
POST/api/qr/ai/generate/server消费者 AI：服务器端 LLM 密钥，按额度计费。
GET/api/qr/templates列出 118 个预置模板（可选 ?category=…）。
POST/api/qr/templates/{templateId}使用模板 ID 渲染二维码，可选覆盖参数。
POST/api/qr/content/wifi辅助：构建 WiFi 二维码载荷字符串。
POST/api/qr/content/vcard辅助：构建 vCard 载荷字符串。
POST/api/qr/content/geo辅助：构建地理位置载荷字符串。
GET/api/qr/ai/providers列出支持的 LLM 提供商和模型。
GET/api/ping健康检查（匿名）。

认证请求头

RapidAPI

X-RapidAPI-Proxy-Secret: <secret>

内部 BFF（消费者网站）

X-Internal-Service-Secret: <secret>
X-Internal-Customer-Id:    <customer id>
X-Internal-Ts:             <unix seconds>
X-Internal-Signature:      <HMAC-SHA256(signing-key, "{customerId}.{ts}")>

防重放 TTL：60 秒。由 Next.js 前端在内部使用，你永远不需要手动设置。

错误信封

所有非 2xx 响应的结构都保持稳定：

{
  "success": false,
  "error": "Content length (5000) exceeds maximum allowed (4296 characters).",
  "code": "CONTENT_TOO_LONG",
  "field": "content"
}

当失败指向某个具体输入时，会设置 field。

速率限制

档位每分钟说明
RapidAPI 常规60文档、ping、辅助端点
RapidAPI 生成30/api/qr/generate
RapidAPI AI15外部 LLM 调用
消费者常规120按客户 ID
消费者生成60按客户 ID
消费者 AI30按客户 ID

为了保护 Azure 免费档，还设有全局的每分钟上限。触及上限时，你会收到带 Retry-After 请求头的 429。

输出格式

png（默认，base64）、jpg、svg、pdf、webp。设置 "responseType": "binary" 可直接下载文件，而不是在 JSON 中接收 base64。