> ## 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` 형태와 enum 기반의 모든 옵션은 [Render settings reference](/en/render-settings-reference)에서 확인할 수 있습니다.

## 프리셋을 사용해야 하는 경우

<Columns cols={2}>
  <Card title="프리셋을 사용해야 하는 경우…" icon="check">
    여러 프로젝트에서 동일한 룩이 필요하고, 한 곳에서 업데이트하고
    싶을 때.
  </Card>

  <Card title="프로젝트 설정을 사용해야 하는 경우…" icon="sliders" href="/ko/api/project-settings">
    공유할 가치가 없는 프로젝트 로컬 오버라이드가 필요할 때.
  </Card>
</Columns>

## 엔드포인트

| Method   | Path                  | Purpose                     |
| -------- | --------------------- | --------------------------- |
| `GET`    | `/presets`            | 인증된 계정의 프리셋 목록을 조회합니다.      |
| `POST`   | `/presets`            | 새 프리셋을 생성합니다.               |
| `GET`    | `/presets/{presetId}` | 단일 프리셋을 가져옵니다.              |
| `PATCH`  | `/presets/{presetId}` | 이름/본문을 업데이트하거나 기본값으로 설정합니다. |
| `DELETE` | `/presets/{presetId}` | 프리셋을 삭제합니다.                 |

전체 요청 및 응답 스키마는 사이드바의 **API reference**에서 확인할 수 있습니다.

## 프리셋 생성

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

응답에는 새 `presetId`가 포함됩니다. 이를 저장해 두고 프로젝트 또는 내보내기에서 참조하세요.

<Tip>
  모든 `POST`에 멱등성 키를 함께 사용하세요. 동일한 키를 동일한
  payload와 함께 재사용하면 중복을 생성하는 대신 기존 프리셋을 반환합니다.
</Tip>

## 유효한 프리셋 필드 확인

프리셋은 서버 측에서 `KaraokePresetSchema`에 대해 검증됩니다. SDK는 이 스키마를 내보내므로 런타임에 JSON Schema로 변환할 수 있습니다:

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

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

CLI에서:

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

에이전트 작성자는 프리셋을 변경하기 전에 이를 호출해 모델이 모든 유효한 필드와 값 타입을 알 수 있게 해야 합니다.

사람이 읽기 쉬운 참고 자료:

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

## 프리셋 업데이트

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

`name`과 `preset` 중 어떤 부분집합이든 전달할 수 있습니다. 포함하지 않은 필드는 변경되지 않습니다.

## 기본 프리셋 설정

각 계정에는 기본 프리셋이 최대 1개까지 있으며, 새 프로젝트에 자동으로 적용됩니다.

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

새 기본값을 설정하면 이전 기본값은 자동으로 해제됩니다.

## 프리셋 적용

프리셋은 다음 세 곳에서 참조할 수 있습니다:

| Where       | Field                                              |
| ----------- | -------------------------------------------------- |
| 프로젝트 생성 시   | `POST /projects`의 `presetId`                       |
| 프로젝트에서 언제든지 | `PATCH /projects/{projectId}/settings`의 `presetId` |
| 내보내기 시      | `POST /projects/{projectId}/exports`의 `presetId`   |

내보내기 예시:

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

## 프리셋 삭제

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

<Warning>
  프리셋을 삭제해도 이전에 해당 프리셋으로 렌더링된 프로젝트나 내보내기에는
  영향이 없습니다. 삭제된 프리셋을 참조하는 향후 내보내기는 실패합니다.
</Warning>

## 다음 단계

* [Render settings reference](/en/render-settings-reference) — 모든 공유 필드 경로와 enum 값
* [Media](/ko/api/media) — 프리셋 본문에서 참조됨
* [Project settings](/ko/api/project-settings) — 프리셋을 프로젝트에 적용
* [CLI presets](/ko/cli/presets) — 터미널에서 동일한 흐름
* [SDK presets](/ko/sdk/presets) — TypeScript에서 동일한 엔드포인트