> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 模板

> 保存可复用的二维码设计，并将其应用到新的二维码上。

> [!NOTE]
>
> 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` | [复制模板](#复制模板) |

## 应用模板

在[创建二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)时传入 `templateId`。模板的设计会应用到新二维码上。您在同一请求中发送的任何设计对象都会合并到模板设计之上。

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

## 请求头

**Authorization** `string` *required*

`Bearer` 后跟您的 API 密钥。请参阅[身份验证](https://docs.getqr.com/zh/api/authentication.md)。

**Content-Type** `string`

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

## 模板对象

**id** `string`

模板的 ID，例如 `qrt_8Hs2mQvKpLd4RtYw`。

**name** `string`

选择模板时显示的名称。

**designKind** `string`

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

**design** `object`

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

**properties**

**styles** `object | null`

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

**frameOptions** `object | null`

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

**logoOptions** `object | null`

中心 Logo。

**createdAt** `string`

创建日期，ISO 8601 格式。

**updatedAt** `string`

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

## 列出模板

`GET /api/v1/templates`

返回工作区中的模板，按从新到旧排序。列表支持分页：请参阅[分页](https://docs.getqr.com/zh/api/introduction.md#分页)。

**page** `integer` (default: 1)

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

**pageSize** `integer` (default: 100)

每页结果数，1 到 100。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/templates?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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`。设计字段会与[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)中列出的目录进行校验，因此未知的形状、边框或 Logo 会被拒绝，并返回 `422`。

**name** `string` *required*

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

**styles** `object`

点和定位角的形状与颜色。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**frameOptions** `object`

绘制在二维码周围的边框及其行动号召文字。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

**logoOptions** `object`

放在中心的 Logo：推荐 Logo，或通过[文件](https://docs.getqr.com/zh/api/endpoints/files.md)以 `logo` 用途上传的您自己的文件。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

```bash cURL theme={null}
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" }
    }
  }'
```

```json 201 theme={null}
{
  "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}`

**templateId** `string` *required*

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

```bash cURL theme={null}
curl "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "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` 会保留其余设置。已经用该模板创建的二维码会保留创建时的设计。

**templateId** `string` *required*

模板的 ID。

**name** `string`

新名称，1 到 40 个字符。

**styles** `object`

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

**frameOptions** `object`

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

**logoOptions** `object`

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

```bash cURL theme={null}
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)" }'
```

```json 200 theme={null}
{
  "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}`

删除模板。用它创建的二维码会保留各自的设计。

**templateId** `string` *required*

模板的 ID。

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{ "id": "qrt_8Hs2mQvKpLd4RtYw", "deleted": true }
```

## 复制模板

`POST /api/v1/templates/{templateId}/duplicate`

创建一个名为 `<name> copy` 的副本，它拥有独立的 ID 和可自由编辑的独立设计。无需请求体。返回 `201 Created`。

**templateId** `string` *required*

要复制的模板的 ID。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/templates/qrt_8Hs2mQvKpLd4RtYw/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 201 theme={null}
{
  "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"
}
```

## 常见问题

> [accordion] 404 "QR template not found."
>
> 该 `templateId` 与您工作区中的任何模板都不匹配。请从[列出模板](#列出模板)中获取。

> [accordion] 创建或更新模板时返回 422
>
> 某个设计字段与目录不匹配，例如未知的点类型、边框或推荐 Logo。消息会指出该字段。请参阅[自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)。

> [accordion] 创建二维码时返回 422 art\_template\_unsupported
>
> 该模板使用的是 Branded design 或 AI design。请改为应用 `designKind` 为 `custom` 的模板。

## 后续步骤

> [card] [自定义设计](https://docs.getqr.com/zh/api/guides/customization.md)

> [card] [二维码](https://docs.getqr.com/zh/api/endpoints/qr-codes.md)

> [card] [应用中的模板](https://docs.getqr.com/zh/templates/save-template.md)

> [card] [文件](https://docs.getqr.com/zh/api/endpoints/files.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.