模板 - GetQR Docs

curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

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

模板用于保存可复用的设计：styles、frameOptions 和 logoOptions。模板从不包含内容或链接。工作区中的所有人共享模板。

方法	路径	说明
`GET`	`/api/v1/templates`	列出模板
`POST`	`/api/v1/templates`	创建模板
`GET`	`/api/v1/templates/{templateId}`	获取模板
`PATCH`	`/api/v1/templates/{templateId}`	更新模板
`DELETE`	`/api/v1/templates/{templateId}`	删除模板
`POST`	`/api/v1/templates/{templateId}/duplicate`	复制模板

应用模板

在创建二维码时传入 templateId。模板的设计会应用到新二维码上。您在同一请求中发送的任何设计对象都会合并到模板设计之上。

复制而非关联。 二维码会保留自己的一份设计副本。之后编辑或删除模板不会影响它。
仅限自定义设计。 designKind 为 branded 或 ai 的模板无法通过 API 应用，会返回 422（art_template_unsupported）。
仅限您的工作区。 未知的模板或其他工作区的模板会返回 404。

请求头

string

必填

Bearer 后跟您的 API 密钥。请参阅身份验证。

string

application/json。带请求体的请求必须提供。

模板对象

string

模板的 ID，例如 qrt_8Hs2mQvKpLd4RtYw。

string

选择模板时显示的名称。

string

只读。custom 表示 API 可以完整编辑的设计。branded 和 ai 表示在控制台中创建的 Branded design 或 AI design：其图案无法通过 API 编辑，在您更改其他设计字段时会被保留。

object

已保存的设计。每个字段的结构都与同名的请求字段相同，因此可以直接回传。

显示 properties

object | null

点和定位角的形状与颜色。

object | null

二维码周围的边框及其行动号召文字。

object | null

中心 Logo。

string

创建日期，ISO 8601 格式。

string

最后更新日期，ISO 8601 格式。

列出模板

GET /api/v1/templates 返回工作区中的模板，按从新到旧排序。列表支持分页：请参阅分页。

integer

默认值:"1"

要返回的页码，最小为 1。

integer

默认值:"100"

每页结果数，1 到 100。

curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qrt_8Hs2mQvKpLd4RtYw",
      "name": "Brand blue",
      "designKind": "custom",
      "design": {
        "styles": {
          "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
          "backgroundOptions": { "color": "#FFFFFF" }
        },
        "frameOptions": null,
        "logoOptions": null
      },
      "createdAt": "2026-07-20T09:12:00.000Z",
      "updatedAt": "2026-07-20T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

创建模板

POST /api/v1/templates 保存一个新设计。返回 201 Created。设计字段会与自定义设计中列出的目录进行校验，因此未知的形状、边框或 Logo 会被拒绝，并返回 422。

string

必填

选择模板时显示的名称，1 到 40 个字符。

object

点和定位角的形状与颜色。请参阅自定义设计。

object

绘制在二维码周围的边框及其行动号召文字。请参阅自定义设计。

object

放在中心的 Logo：推荐 Logo，或通过文件以 logo 用途上传的您自己的文件。请参阅自定义设计。

curl -X POST "https://getqr.com/api/v1/templates" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand blue",
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    }
  }'

{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}

获取模板

GET /api/v1/templates/{templateId}

string

必填

模板的 ID。可从列表或创建接口的响应中获取。

curl "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-07-20T09:12:00.000Z"
}

更新模板

PATCH /api/v1/templates/{templateId} 只发送您要更改的字段。设计对象会合并到已保存的设计中，因此部分 styles 会保留其余设置。已经用该模板创建的二维码会保留创建时的设计。

string

必填

模板的 ID。

string

新名称，1 到 40 个字符。

object

样式更改，会合并到已保存的 styles 中。

object

边框更改，会合并到已保存的边框设置中。

object

Logo 更改，会合并到已保存的 Logo 设置中。

curl -X PATCH "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Brand blue (2026)" }'

{
  "id": "qrt_8Hs2mQvKpLd4RtYw",
  "name": "Brand blue (2026)",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-07-20T09:12:00.000Z",
  "updatedAt": "2026-08-14T09:00:00.000Z"
}

删除模板

DELETE /api/v1/templates/{templateId} 删除模板。用它创建的二维码会保留各自的设计。

string

必填

模板的 ID。

curl -X DELETE "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qrt_8Hs2mQvKpLd4RtYw", "deleted": true }

复制模板

POST /api/v1/templates/{templateId}/duplicate 创建一个名为 <name> copy 的副本，它拥有独立的 ID 和可自由编辑的独立设计。无需请求体。返回 201 Created。

string

必填

要复制的模板的 ID。

curl -X POST "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qrt_2Kd9pLm4Xs7BnVcQ",
  "name": "Brand blue copy",
  "designKind": "custom",
  "design": {
    "styles": {
      "dotsOptions": { "type": "rounded", "color": "#1E40AF" },
      "backgroundOptions": { "color": "#FFFFFF" }
    },
    "frameOptions": null,
    "logoOptions": null
  },
  "createdAt": "2026-08-14T09:30:00.000Z",
  "updatedAt": "2026-08-14T09:30:00.000Z"
}

常见问题

404 "QR template not found."

该 templateId 与您工作区中的任何模板都不匹配。请从列出模板中获取。

创建或更新模板时返回 422

某个设计字段与目录不匹配，例如未知的点类型、边框或推荐 Logo。消息会指出该字段。请参阅自定义设计。

创建二维码时返回 422 art_template_unsupported

该模板使用的是 Branded design 或 AI design。请改为应用 designKind 为 custom 的模板。

API

模板

应用模板

请求头

模板对象

列出模板

创建模板

获取模板

更新模板

删除模板

复制模板

常见问题

后续步骤

自定义设计

二维码

应用中的模板

文件

​应用模板

​请求头

​模板对象

​列出模板

​创建模板

​获取模板

​更新模板

​删除模板

​复制模板

​常见问题

​后续步骤

自定义设计

二维码

应用中的模板

文件

应用模板

请求头

模板对象

列出模板

创建模板

获取模板

更新模板

删除模板

复制模板

常见问题

后续步骤