自定义设计

GetQR API 目前处于 Beta 阶段，仅向部分工作区开放。正式发布前，细节可能会有所变化。

创建或更新二维码时，可以使用可选的 styles、frameOptions 和 logoOptions 对象设置样式。所有字段都是可选的，未提供的字段会使用默认值。这三个对象同样适用于二维码、模板和批量创建。未知的形状、边框或 Logo 会被拒绝，并返回 422。

设计对象示例

{
  "styles": {
    "dotsOptions": { "type": "rounded", "color": "#000000" },
    "backgroundOptions": { "color": "#ffffff" },
    "cornersSquareOptions": { "type": "dot", "color": "#000000" },
    "cornersDotOptions": { "type": "dot", "color": "#000000" }
  },
  "frameOptions": { "id": "card", "text": "Scan me!", "color": "#000000", "textColor": "#ffffff" },
  "logoOptions": { "type": "suggested", "id": "logo-google", "scalePercent": 25 }
}

将它与二维码的其他字段一起发送：

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" } },
    "frameOptions": { "id": "card", "text": "Scan me!" },
    "logoOptions": { "type": "suggested", "id": "logo-website-3" }
  }'

样式

styles 对象用于设置图案的形状和颜色。

字段	取值
`dotsOptions.type`	主体点的形状：`square`、`dots`、`rounded`、`classy`、`classy-rounded`、`extra-rounded`
`cornersSquareOptions.type`	角方块（眼框）的形状：`square`、`rounded`、`dot`、`classy-rounded`
`cornersDotOptions.type`	角点（眼球）的形状：`square`、`dot`、`dots`、`rounded`、`classy`
`dotsOptions.color`	前景色。默认为 `#000000`。
`backgroundOptions.color`	背景色。默认为 `#ffffff`。
`cornersSquareOptions.color`, `cornersDotOptions.color`	可以发送，但不会生效：定位角始终使用 `dotsOptions.color`。

颜色。 只接受十六进制值：#RGB 或 #RRGGBB。
纠错级别。 始终为 Q，且不能作为输入。发送 styles.qrOptions 会返回 422。
Branded design 和 AI design。 无法通过 API 设置。发送 styles.logoQrArt 会返回 422。
内容。 styles.data 会被忽略。图片始终编码二维码自身的内容。

前景色和背景色之间要保持足够的对比度，最好是浅色背景配深色前景。对比度过低的二维码可能无法扫描。请参阅颜色。

边框

frameOptions 对象会在二维码周围添加带有行动号召的装饰性边框。

字段	说明
`id`	发送 `frameOptions` 时必填。边框类型，取自下方列表。`none` 表示不使用边框。
`text`	行动号召文字，最多 12 个字符。默认为 `Scan me!`。
`color`	边框颜色，十六进制。
`textColor`	文字颜色，十六进制。边框显示文字时，必须与 `color` 不同，除非这组颜色是该边框的内置颜色预设之一。
`borderColor`	描边颜色，十六进制。
`fingerPrintColor`	边框图标的强调色，十六进制。

通用边框

none, card, card-1, card-2, card-3, card-4, card-5, card-7, card-8, card-9, card-10, card-11, card-12, card-13, card-14, card-15, card-hor, wreath, envelope, waitress, coffee-cup, scooter, clipboardcard-hor 不显示文字。

按二维码类型分组的边框

类型	带文字的边框	不带文字的边框
App Link	`app-3`	`app-1`, `app-2`
vCard	`contact-1`, `contact-5`	`contact-2`, `contact-3`, `contact-4`
Email	`email-1`	`email-2`, `email-3`, `email-4`, `email-5`
Feedback	—	`feedback-1`, `feedback-2`, `feedback-3`, `feedback-4`, `feedback-5`
Image	—	`image-1`, `image-2`, `image-3`, `image-4`, `image-5`, `image-6`
Location	`location-3`	`location-1`, `location-2`, `location-4`, `location-5`, `location-6`
Multi-Link	`multilink-3`	`multilink-1`, `multilink-2`
Payment	—	`payment-1`, `payment-2`, `payment-3`, `payment-4`, `payment-5`
PDF	`pdf-1`	`pdf-2`, `pdf-3`, `pdf-4`
SMS	`sms-3`, `sms-5`, `sms-7`	`sms-1`, `sms-2`, `sms-4`, `sms-6`
Social Media	`social-3`	`social-1`, `social-2`, `social-4`
Video	`video-1`, `video-3`	`video-2`, `video-4`, `video-5`, `video-6`
Website	`website-1`	`website-2`, `website-3`, `website-4`, `website-5`
WhatsApp	`whatsapp-2`	`whatsapp-1`, `whatsapp-3`, `whatsapp-4`
WiFi	—	`wifi-1`, `wifi-2`, `wifi-3`, `wifi-4`

任何边框都可以用于任何类型的二维码。此分组与控制台一致。

不带文字的边框在控制台中没有行动号召字段，并且 textColor 必须与 color 不同的规则对它们不适用。

Logo

logoOptions 对象用于在二维码中心放置 Logo。通过设置 type 选择 Logo 的种类。

自定义 Logo

上传图片

使用 "target": "logo" 通过文件注册图片，然后将文件上传到返回的 uploadUrl。

引用文件

将 type 设为 uploaded，并将 fileId 设为返回的 fileId。fileId 为必填项，且必须是文件端点返回的 ID。

{ "logoOptions": { "type": "uploaded", "fileId": "file_7bQ2xR9mKp", "scalePercent": 35 } }

未知的文件、未完成的上传或使用其他用途上传的文件都会被拒绝。

Logo 大小

scalePercent 以二维码尺寸的百分比设置 Logo 大小。取值为 15 到 45 之间的整数，默认值为 25。其他值（包括 0.25 这样的比例值）会返回 422。

更新设计

部分更新。 在更新二维码时，styles、frameOptions 和 logoOptions 会合并到已保存的设计中。部分对象只会更改其中指定的内容。
更换 Logo。 选择其他 Logo 会替换已保存的 Logo，但保留其 scalePercent。
模板。 创建时提供 templateId，您发送的字段会合并到模板设计之上。请参阅模板。
Branded design 和 AI design。 designKind 为 branded 或 ai 的二维码是在控制台中创建的。API 无法编辑其图案，但在您更改其他字段时会保留它。
读取设计。 响应会在 design 下返回已保存的设计，其结构与请求字段相同，因此可以直接回传。

常见问题

422 "Error correction is always Q and is not an input"

从请求中移除 styles.qrOptions。

422 "Frame caption is at most 12 characters"

将 frameOptions.text 缩短到 12 个字符以内。

422 "Frame caption color must differ from the frame color"

在显示文字的边框上，textColor 与 color 相同。请选择一个对比明显的 textColor。

422 "Logo scale is a whole number from 15 to 45"

请以整数百分比发送 scalePercent，例如 25，而不是 0.25。

定位角颜色没有变化

定位角始终使用 dotsOptions.color。cornersSquareOptions.color 和 cornersDotOptions.color 不会生效。

API

设计对象示例

样式

边框

Logo

推荐 Logo

自定义 Logo

Logo 大小

更新设计

常见问题

后续步骤

二维码

模板

文件

设计概览

​设计对象示例

​样式

​边框

​Logo

​推荐 Logo

​自定义 Logo

​Logo 大小

​更新设计

​常见问题

​后续步骤

二维码

模板

文件

设计概览

设计对象示例

样式

边框

Logo

推荐 Logo

自定义 Logo

Logo 大小

更新设计

常见问题

后续步骤