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

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

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

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

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

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

​
Эндпоинты

MethodPathPurpose
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
  }'
При установке нового значения по умолчанию предыдущее автоматически снимается.

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

Ссылаться на пресет можно в трёх местах:
WhereField
При создании проекта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