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

> Configurações de renderização reutilizáveis — criar, atualizar, listar e definir o padrão da conta

Um preset é uma configuração de renderização reutilizável — fundo, estilo de legendas, layout — que você pode aplicar a qualquer projeto ou exportação. Use presets quando você tiver uma aparência consistente em várias faixas.

Veja [Render settings reference](/en/render-settings-reference) para o formato completo de
`preset` e todas as opções baseadas em enums.

## Quando usar um preset

<Columns cols={2}>
  <Card title="Use um preset quando…" icon="check">
    Você quer a mesma aparência em vários projetos e precisa atualizá-la em um só
    lugar.
  </Card>

  <Card title="Use as configurações do projeto quando…" icon="sliders" href="/pt/api/project-settings">
    Você precisa de substituições locais do projeto que não valem a pena compartilhar.
  </Card>
</Columns>

## Endpoints

| Método   | Caminho               | Finalidade                                        |
| -------- | --------------------- | ------------------------------------------------- |
| `GET`    | `/presets`            | Listar presets da conta autenticada.              |
| `POST`   | `/presets`            | Criar um novo preset.                             |
| `GET`    | `/presets/{presetId}` | Buscar um único preset.                           |
| `PATCH`  | `/presets/{presetId}` | Atualizar o nome, o corpo ou definir como padrão. |
| `DELETE` | `/presets/{presetId}` | Excluir um preset.                                |

Os esquemas completos de requisição e resposta estão disponíveis em **API reference** na barra lateral.

## Criar um preset

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

A resposta inclui o novo `presetId`. Armazene-o e referencie-o em projetos ou exportações.

<Tip>
  Associe cada `POST` a uma chave de idempotência. Reutilizar a mesma chave com o mesmo
  payload retorna o preset original em vez de criar um duplicado.
</Tip>

## Descobrir campos válidos do preset

Presets são validados no servidor em relação ao `KaraokePresetSchema`. O SDK exporta esse schema para que você possa convertê-lo para JSON Schema em tempo de execução:

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

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

Pelo CLI:

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

Autores de agentes devem chamar isso antes de alterar presets para que o modelo conheça todos os campos válidos e tipos de valor.

Referência legível:

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

## Atualizar um preset

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

Passe qualquer subconjunto de `name` e `preset`. Campos que você não incluir permanecem inalterados.

## Definir o preset padrão

Cada conta tem, no máximo, um preset padrão, aplicado automaticamente a novos projetos.

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

Definir um novo padrão automaticamente remove o padrão anterior.

## Aplicar um preset

Referencie um preset em três lugares:

| Onde                          | Campo                                                |
| ----------------------------- | ---------------------------------------------------- |
| Na criação do projeto         | `presetId` em `POST /projects`                       |
| A qualquer momento no projeto | `presetId` em `PATCH /projects/{projectId}/settings` |
| No momento da exportação      | `presetId` em `POST /projects/{projectId}/exports`   |

Exemplo na exportação:

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

## Excluir um preset

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

<Warning>
  Excluir um preset não afeta projetos ou exportações que tenham sido previamente
  renderizados com ele. Exportações futuras que referenciem o preset excluído falharão.
</Warning>

## O que vem a seguir

* [Render settings reference](/en/render-settings-reference) — todos os caminhos de campos compartilhados e valores de enum
* [Media](/pt/api/media) — referenciado em corpos de presets
* [Project settings](/pt/api/project-settings) — aplicar um preset a um projeto
* [CLI presets](/pt/cli/presets) — o mesmo fluxo pelo terminal
* [SDK presets](/pt/sdk/presets) — os mesmos endpoints em TypeScript