Пресеты

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

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

Используйте пресет, когда…

Вам нужен одинаковый внешний вид для многих проектов и вы хотите обновлять его в одном месте.

Используйте настройки проекта, когда…

Вам нужны локальные переопределения на уровне проекта, которыми не имеет смысла делиться.

Эндпоинты

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

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

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

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. Сохраните его и используйте в проектах или экспортах.

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

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

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

import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();

Из CLI:

youka preset schema --json

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

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

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. Поля, которые вы не включите, останутся без изменений.

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

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

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`

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

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"
  }'

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

curl -X DELETE https://api.youka.io/ru/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"

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

Что дальше

Render settings reference — все общие пути полей и значения enum
Media — используется в телах пресетов
Project settings — применить пресет к проекту
CLI presets — тот же процесс из терминала
SDK presets — те же эндпоинты в TypeScript

Overview

How To

Customization

Audio

Settings

Exporting

Account

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

Используйте пресет, когда…

Используйте настройки проекта, когда…

Эндпоинты

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

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

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

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

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

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

Что дальше

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

Используйте пресет, когда…

Используйте настройки проекта, когда…

​Эндпоинты

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

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

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

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

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

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

​Что дальше

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

Эндпоинты

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

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

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

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

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

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

Что дальше