**版本：202601**

# 创建主题自定义模板

**POST** `/openapi/2026-01/themes/:theme_id/theme-templates`

一次调用即创建自定义模板并绑定到对象（商品、专辑）；`relations` 为空则只建不绑。

## 请求

**Path参数**

- `theme_id` string (required)

  模板所属主题 ID

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `type` string (required)

  模板类型，取值之一：`product`、`collection`、`product_coll`、`page`
- `title` string (required)

  模板显示名称
- `relations` string[]

  绑定对象 ID 数组（商品 / 专辑）。空数组 = 只建不绑
- `from` string

  复制来源模板的 suffix，如 default
- `oseid` string

  创建所在的编辑会话 ID
- `selected_all` int32

  是否按 `front_query_params` 全选绑定（而不是在 `relations` 中逐个列出）：0 = 否（默认），1 = 是。取 1 时，目标对象集由 `front_query_params` 圈定
- `front_query_params` object

  `selected_all` = 1 时用于圈定目标对象集的筛选条件；其它情况忽略

  - `search_keyword` string

    圈定目标对象集时的关键词过滤条件；仅在 `selected_all` = 1 时生效
  - `collection_id` string

    圈定目标对象集时的专辑过滤条件；仅在 `selected_all` = 1 时生效

```json
{
  "type": "string",
  "title": "string",
  "relations": [
    "string"
  ],
  "from": "string",
  "oseid": "string",
  "selected_all": 0,
  "front_query_params": {
    "search_keyword": "string",
    "collection_id": "string"
  }
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `theme_template` object

    创建出的主题模板。仅 `id` 有值，其余字段均为空；需要完整信息请调用模板列表接口

    - `id` string

      模板唯一 ID
    - `theme_id` string

      所属主题 ID
    - `store_id` string

      店铺 ID
    - `doc_id` string

      底层文档（模板文件）ID
    - `type` string

      模板类型：`product`（绑定商品的商品详情页）、`collection`（专辑详情页）、`product_coll`（绑定专辑的商品详情页）、`page`（自定义页，旧版兼容）
    - `title` string

      模板显示名称
    - `suffix` string

      模板路由后缀
    - `from` string

      模板创建来源（复制源模板的 suffix）
    - `obj_id` string

      **首个**绑定对象的 ID（商品 / 专辑 / 自定义页 id）；未绑定任何对象时为空。一个模板可绑定多个对象，总数见 `count` —— 该字段不会列出全部对象
    - `obj_title` string

      首个绑定对象的显示标题（与 `obj_id` 指向同一对象）
    - `source` string

      数据操作来源：该记录由哪个入口写入。只读；与 `from`（复制自哪个模板）不是一回事
    - `created_at` string

      创建时间
    - `updated_at` string

      更新时间
    - `icon` string

      模板图标 URL
    - `count` string

      绑定到该模板的对象数量，以十进制字符串返回（如 `12`），不是数字类型

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "theme_template": {
      "id": "string",
      "theme_id": "string",
      "store_id": "string",
      "doc_id": "string",
      "type": "string",
      "title": "string",
      "suffix": "string",
      "from": "string",
      "obj_id": "string",
      "obj_title": "string",
      "source": "string",
      "created_at": "string",
      "updated_at": "string",
      "icon": "string",
      "count": "string"
    }
  }
}
```