用户 API 密钥

如果你更希望使用在 /dashboard/keys 签发的自己的密钥进行认证，而不是 RapidAPI 市场的代理密钥，本页正适合你。同一个引擎，换一扇门进入。

市场客户应继续针对 api.qr-branding.com 使用 X-RapidAPI-Proxy-Secret。消费者密钥网关位于 qr-branding.com/api/v1/*，绝不会干扰市场渠道。

基础 URL

https://qr-branding.com/api/v1

认证

在每个请求中发送你的密钥：

X-API-Key: qrb_…

密钥会在边缘（CF Pages）与我们数据库中的哈希值进行比对验证，引擎本身永远看不到你的明文密钥。

如果密钥缺失、格式错误或已被吊销，你会收到：

{ "success": false, "error": "Key not recognised, revoked, or malformed.", "code": "invalid_api_key" }

（状态码为 401。）

前提条件：Studio 套餐

API 是 Studio 的功能。所有请求（不仅是 AI 请求）都需要有效的 Studio 额度包（购买未满 12 个月且未退款）。如果密钥有效但账户没有 Studio，网关会返回 402，并附上本页和定价页的链接：

{ "success": false, "error": "The QR Branding API is included with Studio. Buy a Studio pack at https://qr-branding.com/pricing to use your key.", "code": "studio_required", "docs": "https://qr-branding.com/docs/api/public-keys", "pricing": "https://qr-branding.com/pricing" }

使用我们的 LLM 密钥进行 AI 生成（POST /api/v1/qr/ai/generate/server）还会从你的 Studio 额度包中扣除 1 个 AI 额度；用完后会收到附带相同链接的 402 out_of_api_credits。其他调用不消耗额度。

可用端点

网关会将 /api/v1/* 下的所有路径转发给引擎。因此：

请求体、响应结构和错误代码与引擎端点完全相同，你收藏的文档页面可以继续使用。

快速测试

curl -X POST https://qr-branding.com/api/v1/qr/generate \
  -H "X-API-Key: qrb_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "content": "https://yourbrand.com", "primaryColor": "#dcc28a", "backgroundColor": "#0a0b0e", "eccLevel": "H" }' \
  --output qr.png --silent --write-out "%{http_code}\n"

如果收到 200，并且磁盘上出现了 qr.png，就大功告成了。

限制

用户密钥适用消费者渠道的按客户限制：

达到限制时会收到带有 Retry-After 头的 429。详情和全局上限见 API 概览。

Multipart 上传

网关只接受 JSON。上传 logo / 背景二进制文件时，请使用 base64 字段（logoBase64、backgroundImageBase64），而不是 multipart/form-data。我们可能会在 v2 中加入原生 multipart 支持。

轮换

生成新密钥并完成部署，然后吊销旧密钥。明文只显示一次，请将其保存到你的密钥管理工具中。

# in your CI / secrets tool
QR_BRANDING_KEY=qrb_new_key_here

当旧密钥从网关收到 401 invalid_api_key 时，说明你的所有服务都已完成迁移，可以确认轮换成功。