---
title: "PUT /templates/{template} — Обновить шаблон"
url: https://lumean.app/developers/docs/api/put-templates-template
locale: ru
description: "Обновить шаблон"
generated: 2026-11-08
operationId: template.update
method: PUT
path: "/templates/{template}"
scopes: [templates.write]
spec_version: 1.0.0
---

# PUT /templates/{template}

**Обновить шаблон**

Частичное обновление шаблона: присылайте только те поля, которые меняете. Метод
принимает и `PUT`, и `PATCH` — поведение одинаковое.

`config` **сливается с текущим вглубь**, а не заменяет его: ключ, который вы не
прислали, останется прежним. Но присланный `config` проверяется схемой сервиса сам
по себе, до слияния, — обязательные поля схемы (`GET /templates/config-options`)
присылайте всегда. Списки сливаются по позиции: чтобы заменить список, пришлите его
целиком. `config` и `service_key` передаются только парой: даже когда сервис не
меняется, его код придётся продублировать.

Изменение шаблона не затрагивает уже созданные заказы: заказ выполняется, повторяется
(`POST /orders/{order}/retry`) и показывается (`template.config` в `GET /orders/{order}`)
с настройками на момент своего создания. Исключение — заказы, созданные до конца
сентября 2026 года: снимка настроек у них нет, они идут по текущему конфигу шаблона
(с наложенным `config_override`), и правка шаблона их затрагивает.

**Требуемое право ключа:** `templates.write`.

- Право ключа: `templates.write`

- Тот же обработчик отвечает и на метод `PATCH`.

## Запрос

```bash
curl -X PUT 'https://api.lumean.app/api/public/templates/{template}' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Диктор — женский, тёплый"
}'
```

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `template` | path | `string` — uuid | обяз. | UUID шаблона — 36 символов, не число. Берётся из поля `id`: его возвращает `POST /templates` при создании, а также `GET /templates` и `GET /templates/browse` в списках. |
| `X-Locale` | header | `string` | — | Язык локализованных текстов ответа (`message`, подписи, причины ошибок), код ISO-639-1. Необязателен; без него — язык аккаунта владельца ключа, затем `Accept-Language`, затем язык по умолчанию. Неизвестный или неподдерживаемый код пропускается так же, как отсутствующий. |
| `X-Timezone` | header | `string` | — | IANA-зона (`Europe/Moscow`), в которой ответ показывает моменты времени — ISO-8601 со смещением. Необязателен; без него даты приходят в UTC. Невалидная зона игнорируется. Применённую зону сервер возвращает в одноимённом заголовке ответа. |

## Тело запроса

Обновление частичное: присылайте только меняемые поля, остальные сохранятся.

Две особенности, из-за которых запрос чаще всего уходит в `422`:

- **`service_key` и `config` ходят парой.** Одно без другого валидация не
  принимает — даже когда сервис вы не меняете, его код придётся продублировать.
- **`config` сливается с текущим вглубь, а не заменяет его.** Ключ, который вы
  не прислали, останется прежним; вернуть его к значению по умолчанию правкой
  шаблона нельзя — только пересозданием.

Content-Type: `application/json`

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `folder_id` | `string` — uuid — nullable | — | UUID папки, в которую переместить шаблон. `null` — перенести в корень. |
| `service_key` | `string` | — | Новый код сервиса. Меняется только вместе с `config` — конфиг валидируется по схеме нового сервиса. |
| `name` | `string` — ≤ 255 симв. | — | Новое название шаблона, до 255 символов. |
| `is_public` | `boolean` | — | Опубликовать шаблон в общем каталоге или снять с публикации. |
| `config` | `object` | — | Меняемые настройки генерации. Сливаются с текущим `config` вглубь: ключ, который вы не прислали, остаётся прежним, списки сливаются по позиции. Проверяются схемой сервиса до слияния, поэтому обязательные поля схемы присылайте всегда. Передаётся только вместе с `service_key`. Допустимая структура — `GET /templates/config-options?service=<код>`. |

**Пример**

```json
{
  "name": "Диктор — женский, тёплый"
}
```

## Сценарии тела

### Только переименовать

Частичное обновление: передаются лишь изменяемые поля, остальные настройки шаблона сохраняются.

```json
{
  "name": "Диктор — женский, тёплый"
}
```

### Подправить настройки голоса

config сливается с текущим вглубь — прислать можно только меняемые ключи. service_key при этом обязателен: одно без другого валидация не принимает.

```json
{
  "service_key": "elevenlabs",
  "config": {
    "tts_settings": {
      "voice_settings": {
        "stability": 0.7,
        "speed": 1.1
      }
    }
  }
}
```

### Сменить сервис

Присылайте полный config нового сервиса: старые ключи не исчезают (слияние идёт вглубь), но по схеме нового сервиса они уже ничего не значат.

```json
{
  "service_key": "heygen",
  "config": {
    "tts_settings": {
      "voice_id": "1bd001e7e50f421d891986aad5158bc8",
      "speed": 1
    }
  }
}
```

## Ответы

### 200 — Шаблон обновлён

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `Template` | обяз. | Шаблон после обновления — с уже слитым `config`. Сверьтесь с ним, если присылали частичные настройки. |
| `data.id` | `string` | обяз. | UUID шаблона. Его кладут в `template_id` при создании заказа. |
| `data.user_id` | `integer` | обяз. | ID владельца шаблона. |
| `data.slug` | `string` | обяз. | Короткий публичный идентификатор для расшаривания. `null` у шаблона, которым не делились. |
| `data.name` | `string` | обяз. | Название шаблона — только для человека, на поведение генерации не влияет. |
| `data.service_key` | `string` | обяз. | Код сервиса, по схеме которого валидируется `config`: `elevenlabs`, `lumimg` и т. д. |
| `data.service` | `Service \| null` — nullable | обяз. | Сервис шаблона справочно: название и тарификация, без схем конфигурации. `null` означает, что сервиса с таким кодом больше нет. |
| `data.config` | `object` | обяз. | Настройки генерации: голос, модель, скорость и прочее — набор ключей задаёт сервис. Допустимые значения смотрите в `GET /templates/config-options?service=<код>`, значение вне схемы отклоняется с `422`. В заказе (`template` в `GET /orders/{order}`) это настройки самого заказа — снимок на момент его создания с `config_override`, а не текущий конфиг шаблона (у заказов, созданных до конца сентября 2026 года, — текущий конфиг шаблона с `config_override`). |
| `data.is_public` | `boolean` | обяз. | Опубликован ли шаблон в общем каталоге. |
| `data.folder_id` | `string` | обяз. | UUID папки, в которой лежит шаблон, либо `null` для корня. Структура папок видна в `GET /templates/browse`. |
| `data.created_at` | `string` — date-time — nullable | обяз. | Когда шаблон создан, ISO 8601. |
| `data.updated_at` | `string` — date-time — nullable | обяз. | Когда шаблон последний раз менялся, ISO 8601. |

**Пример**

```json
{
  "success": true,
  "message": "Template updated",
  "data": {
    "id": "7e2a4c1d-8b3f-4a5e-9c6d-1f2e3a4b5c6d",
    "user_id": 501,
    "slug": null,
    "name": "Narrator Voice (EN) v2",
    "service_key": "elevenlabs",
    "config": {
      "tts_settings": {
        "model_id": "eleven_multilingual_v2",
        "voice_id": "21m00Tcm4TlvDq8ikWAM",
        "mode": "mode_v1",
        "language_code": "en",
        "advanced_voice_settings": true,
        "voice_settings": {
          "stability": 0.6,
          "similarity_boost": 0.75,
          "use_speaker_boost": true
        }
      }
    },
    "is_public": false,
    "folder_id": null,
    "created_at": "2026-06-01T10:00:00+00:00",
    "updated_at": "2026-07-17T16:45:00+00:00"
  }
}
```

### 401 — Невалидный или отсутствующий X-API-KEY

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. |

**Пример**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

### 403 — Нет доступа к шаблону

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 404 — Шаблон не найден

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `reason` | `string` | — | Машиночитаемая причина — приходит у бизнес-отказов (например, `invalid_order_status`); у прочих ошибок поля нет. Ветвите обработку по нему, а не по тексту сообщения. |
| `error_code` | `string` | — | Тот же машинный код, что в `reason`, — второе имя поля. Приходит вместе с `reason`, значения всегда совпадают. |

**Пример**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

### 422 — Ошибка валидации

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Сводка ошибок валидации словами, на языке ответа (`X-Locale`). |
| `errors` | `object` | обяз. | Разбор по полям: ключ — поле запроса, значение — список претензий к нему. |
| `errors.*` | `array<string>` — произвольные ключи | — |  |

**Пример**

```json
{
  "message": "string",
  "errors": {
    "key": [
      "string"
    ]
  }
}
```

---

- Эта же страница в браузере: https://lumean.app/developers/docs/api/put-templates-template
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md