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

# Пресеты

> Переиспользуемые конфигурации рендера — создавайте, обновляйте, просматривайте список и задавайте значение по умолчанию для аккаунта

Пресет — это переиспользуемая конфигурация рендера (фон, стиль субтитров, компоновка), которую можно применить к любому проекту или экспорту. Используйте пресеты, когда вам нужен единый внешний вид для множества треков.

Полное описание структуры `preset` и всех опций на основе enum см. в [справочнике настроек рендера](/en/render-settings-reference).

## Когда использовать пресет

<Columns cols={2}>
  <Card title="Используйте пресет, когда…" icon="check">
    Вам нужен одинаковый внешний вид для многих проектов и вы хотите обновлять
    его в одном месте.
  </Card>

  <Card title="Используйте настройки проекта, когда…" icon="sliders" href="/ru/api/project-settings">
    Вам нужны локальные переопределения на уровне проекта, которыми не имеет
    смысла делиться.
  </Card>
</Columns>

## Эндпоинты

| Method   | Path                  | Purpose                                            |
| -------- | --------------------- | -------------------------------------------------- |
| `GET`    | `/presets`            | Список пресетов для аутентифицированного аккаунта. |
| `POST`   | `/presets`            | Создать новый пресет.                              |
| `GET`    | `/presets/{presetId}` | Получить один пресет.                              |
| `PATCH`  | `/presets/{presetId}` | Обновить имя, тело или назначить по умолчанию.     |
| `DELETE` | `/presets/{presetId}` | Удалить пресет.                                    |

Полные схемы запросов и ответов доступны в разделе **API reference** в сайдбаре.

## Создать пресет

```bash theme={null}
curl -X POST https://api.youka.io/ru/api/v1/presets \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: create-neon-night-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "preset": {
      "background": {
        "type": "gradient",
        "colors": ["#12001f", "#2f0a57"],
        "angle": 90
      },
      "singerTextStyles": {
        "0": {
          "fontFamily": "Inter",
          "textColor": "#00f5ff",
          "effectColor": "#ff4fd8"
        }
      }
    },
    "isDefault": false
  }'
```

Ответ включает новый `presetId`. Сохраните его и используйте в проектах или экспортах.

<Tip>
  Для каждого `POST` используйте ключ идемпотентности. Повторное использование
  одного и того же ключа с тем же payload вернёт исходный пресет вместо создания
  дубликата.
</Tip>

## Как узнать допустимые поля пресета

Пресеты валидируются на стороне сервера по `KaraokePresetSchema`. SDK экспортирует эту схему, чтобы вы могли конвертировать её в JSON Schema во время выполнения:

```ts theme={null}
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
```

Из CLI:

```bash theme={null}
youka preset schema --json
```

Авторам агентов следует вызывать это перед изменением пресетов, чтобы модель знала все допустимые поля и типы значений.

Справочник в человекочитаемом виде:

* [Render settings reference](/en/render-settings-reference)
* [CLI presets](/ru/cli/presets)
* [SDK presets](/ru/sdk/presets)

## Обновить пресет

```bash theme={null}
curl -X PATCH https://api.youka.io/ru/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night v2",
    "preset": {
      "singerTextStyles": {
        "0": {
          "textColor": "#ff2a2a"
        }
      }
    }
  }'
```

Передайте любой поднабор `name` и `preset`. Поля, которые вы не включите, останутся без изменений.

## Установить пресет по умолчанию

У каждого аккаунта может быть не более одного пресета по умолчанию; он автоматически применяется к новым проектам.

```bash theme={null}
curl -X PATCH https://api.youka.io/ru/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isDefault": true
  }'
```

При установке нового значения по умолчанию предыдущее автоматически снимается.

## Применить пресет

Ссылаться на пресет можно в трёх местах:

| Where                    | Field                                               |
| ------------------------ | --------------------------------------------------- |
| При создании проекта     | `presetId` в `POST /projects`                       |
| В любой момент в проекте | `presetId` в `PATCH /projects/{projectId}/settings` |
| Во время экспорта        | `presetId` в `POST /projects/{projectId}/exports`   |

Пример при экспорте:

```bash theme={null}
curl -X POST https://api.youka.io/ru/api/v1/projects/prj_abc/exports \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "preset_abc123",
    "resolution": "1080p",
    "quality": "high"
  }'
```

## Удалить пресет

```bash theme={null}
curl -X DELETE https://api.youka.io/ru/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
```

<Warning>
  Удаление пресета не влияет на проекты или экспорты, которые ранее были
  отрендерены с ним. Будущие экспорты, которые ссылаются на удалённый пресет,
  завершатся ошибкой.
</Warning>

## Что дальше

* [Render settings reference](/en/render-settings-reference) — все общие пути полей и значения enum
* [Media](/ru/api/media) — используется в телах пресетов
* [Project settings](/ru/api/project-settings) — применить пресет к проекту
* [CLI presets](/ru/cli/presets) — тот же процесс из терминала
* [SDK presets](/ru/sdk/presets) — те же эндпоинты в TypeScript