Presets

A preset is a reusable render configuration — background, subtitle style, layout — that you can apply to any project or export. Use presets when you have a consistent look across many tracks. See Render settings reference for the full preset shape and every enum-backed option.

When to use a preset

Use a preset when…

You want the same look across many projects and need to update it in one place.

Use project settings when…

You need project-local overrides that aren’t worth sharing.

Endpoints

Method	Path	Purpose
`GET`	`/presets`	List presets for the authenticated account.
`POST`	`/presets`	Create a new preset.
`GET`	`/presets/{presetId}`	Fetch a single preset.
`PATCH`	`/presets/{presetId}`	Update name, body, or set as default.
`DELETE`	`/presets/{presetId}`	Delete a preset.

Full request and response schemas are available under API reference in the sidebar.

Create a preset

curl -X POST https://api.youka.io/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
  }'

The response includes the new presetId. Store it and reference it from projects or exports.

Pair every POST with an idempotency key. Reusing the same key with the same payload returns the original preset instead of creating a duplicate.

Discover valid preset fields

Presets are validated server-side against the KaraokePresetSchema. The SDK exports this schema so you can convert it to JSON Schema at runtime:

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

const jsonSchema = KaraokePresetSchema.toJSONSchema();

From the CLI:

youka preset schema --json

Agent authors should call this before mutating presets so the model knows every valid field and value type. Human-readable reference:

Update a preset

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

Pass any subset of name and preset. Fields you don’t include are left unchanged.

Set the default preset

Every account has at most one default preset, applied automatically to new projects.

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

Setting a new default automatically unsets the previous one.

Apply a preset

Reference a preset in three places:

Where	Field
At project creation	`presetId` in `POST /projects`
At any time on a project	`presetId` in `PATCH /projects/{projectId}/settings`
At export time	`presetId` in `POST /projects/{projectId}/exports`

Example on export:

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

Delete a preset

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

Deleting a preset does not affect projects or exports that were previously rendered with it. Future exports that reference the deleted preset will fail.

What’s next

Render settings reference — all shared field paths and enum values
Media — referenced from preset bodies
Project settings — apply a preset to a project
CLI presets — the same flow from the terminal
SDK presets — the same endpoints in TypeScript

Guides

Resources

API Reference

When to use a preset

Use a preset when…

Use project settings when…

Endpoints

Create a preset

Discover valid preset fields

Update a preset

Set the default preset

Apply a preset

Delete a preset

What’s next

​When to use a preset

Use a preset when…

Use project settings when…

​Endpoints

​Create a preset

​Discover valid preset fields

​Update a preset

​Set the default preset

​Apply a preset

​Delete a preset

​What’s next

When to use a preset

Endpoints

Create a preset

Discover valid preset fields

Update a preset

Set the default preset

Apply a preset

Delete a preset

What’s next