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

# Preset

> Configurazioni di rendering riutilizzabili — crea, aggiorna, elenca e imposta il valore predefinito dell’account

Un preset è una configurazione di rendering riutilizzabile — sfondo, stile dei sottotitoli, layout — che puoi applicare a qualsiasi progetto o export. Usa i preset quando vuoi un aspetto coerente su molte tracce.

Vedi [Render settings reference](/en/render-settings-reference) per la forma completa di
`preset` e tutte le opzioni basate su enum.

## Quando usare un preset

<Columns cols={2}>
  <Card title="Usa un preset quando…" icon="check">
    Vuoi lo stesso aspetto su molti progetti e devi aggiornarlo in un unico
    posto.
  </Card>

  <Card title="Usa le impostazioni del progetto quando…" icon="sliders" href="/it/api/project-settings">
    Ti servono override locali al progetto che non vale la pena condividere.
  </Card>
</Columns>

## Endpoint

| Method   | Path                  | Purpose                                         |
| -------- | --------------------- | ----------------------------------------------- |
| `GET`    | `/presets`            | Elenca i preset per l’account autenticato.      |
| `POST`   | `/presets`            | Crea un nuovo preset.                           |
| `GET`    | `/presets/{presetId}` | Recupera un singolo preset.                     |
| `PATCH`  | `/presets/{presetId}` | Aggiorna nome, body o imposta come predefinito. |
| `DELETE` | `/presets/{presetId}` | Elimina un preset.                              |

Gli schemi completi di richiesta e risposta sono disponibili in **API reference** nella sidebar.

## Crea un preset

```bash theme={null}
curl -X POST https://api.youka.io/it/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
  }'
```

La risposta include il nuovo `presetId`. Conservalo e usalo come riferimento nei progetti o negli export.

<Tip>
  Abbina ogni `POST` a una chiave di idempotenza. Riutilizzare la stessa chiave con lo stesso
  payload restituisce il preset originale invece di crearne un duplicato.
</Tip>

## Scopri i campi validi del preset

I preset vengono validati lato server rispetto a `KaraokePresetSchema`. L’SDK esporta questo schema, così puoi convertirlo in JSON Schema a runtime:

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

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

Dalla CLI:

```bash theme={null}
youka preset schema --json
```

Gli autori di agent dovrebbero chiamarlo prima di modificare i preset, così il modello conosce ogni campo valido e il tipo di valore.

Riferimento leggibile:

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

## Aggiorna un preset

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

Passa qualsiasi sottoinsieme di `name` e `preset`. I campi che non includi restano invariati.

## Imposta il preset predefinito

Ogni account ha al massimo un preset predefinito, applicato automaticamente ai nuovi progetti.

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

Impostare un nuovo predefinito disattiva automaticamente quello precedente.

## Applica un preset

Fai riferimento a un preset in tre punti:

| Dove                                | Campo                                                |
| ----------------------------------- | ---------------------------------------------------- |
| Alla creazione del progetto         | `presetId` in `POST /projects`                       |
| In qualunque momento su un progetto | `presetId` in `PATCH /projects/{projectId}/settings` |
| Al momento dell’export              | `presetId` in `POST /projects/{projectId}/exports`   |

Esempio su export:

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

## Elimina un preset

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

<Warning>
  Eliminare un preset non influisce su progetti o export che sono stati
  renderizzati in precedenza con esso. I futuri export che fanno riferimento al preset eliminato falliranno.
</Warning>

## Cosa fare dopo

* [Render settings reference](/en/render-settings-reference) — tutti i percorsi dei campi condivisi e i valori enum
* [Media](/it/api/media) — referenziati dai body dei preset
* [Project settings](/it/api/project-settings) — applica un preset a un progetto
* [CLI presets](/it/cli/presets) — lo stesso flusso dal terminale
* [SDK presets](/it/sdk/presets) — gli stessi endpoint in TypeScript