Skip to main content
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

MethodPathPurpose
GET/presetsList presets for the authenticated account.
POST/presetsCreate 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:
WhereField
At project creationpresetId in POST /projects
At any time on a projectpresetId in PATCH /projects/{projectId}/settings
At export timepresetId 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