> ## 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.

# Presets

> Reusable render configurations — create, update, list, and set the account default

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](/en/render-settings-reference) for the full
`preset` shape and every enum-backed option.

## When to use a preset

<Columns cols={2}>
  <Card title="Use a preset when…" icon="check">
    You want the same look across many projects and need to update it in one
    place.
  </Card>

  <Card title="Use project settings when…" icon="sliders" href="/en/api/project-settings">
    You need project-local overrides that aren't worth sharing.
  </Card>
</Columns>

## 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

```bash theme={null}
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.

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

## 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:

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

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

From the CLI:

```bash theme={null}
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:

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

## Update a preset

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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

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

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

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Media](/en/api/media) — referenced from preset bodies
* [Project settings](/en/api/project-settings) — apply a preset to a project
* [CLI presets](/en/cli/presets) — the same flow from the terminal
* [SDK presets](/en/sdk/presets) — the same endpoints in TypeScript