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

> Cấu hình render có thể tái sử dụng — tạo, cập nhật, liệt kê và đặt mặc định cho tài khoản

Preset là một cấu hình render có thể tái sử dụng — nền, kiểu phụ đề, bố cục — mà bạn có thể áp dụng cho bất kỳ dự án hoặc lần xuất nào. Hãy dùng preset khi bạn cần một diện mạo nhất quán trên nhiều track.

Xem [Render settings reference](/en/render-settings-reference) để biết đầy đủ cấu trúc
`preset` và mọi tuỳ chọn dựa trên enum.

## Khi nào nên dùng preset

<Columns cols={2}>
  <Card title="Dùng preset khi…" icon="check">
    Bạn muốn cùng một diện mạo trên nhiều dự án và cần cập nhật nó ở một nơi.
  </Card>

  <Card title="Dùng cài đặt dự án khi…" icon="sliders" href="/vi/api/project-settings">
    Bạn cần các ghi đè riêng cho từng dự án và không đáng để chia sẻ.
  </Card>
</Columns>

## Endpoints

| Method   | Path                  | Purpose                                        |
| -------- | --------------------- | ---------------------------------------------- |
| `GET`    | `/presets`            | Liệt kê preset cho tài khoản đã xác thực.      |
| `POST`   | `/presets`            | Tạo một preset mới.                            |
| `GET`    | `/presets/{presetId}` | Lấy một preset cụ thể.                         |
| `PATCH`  | `/presets/{presetId}` | Cập nhật tên, nội dung, hoặc đặt làm mặc định. |
| `DELETE` | `/presets/{presetId}` | Xoá một preset.                                |

Các schema đầy đủ cho request và response có trong **API reference** ở thanh bên.

## Tạo một preset

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

Phản hồi sẽ bao gồm `presetId` mới. Hãy lưu lại và tham chiếu nó từ các dự án hoặc lần xuất.

<Tip>
  Hãy ghép mỗi `POST` với một idempotency key. Dùng lại cùng một key với cùng
  payload sẽ trả về preset ban đầu thay vì tạo bản trùng lặp.
</Tip>

## Khám phá các trường preset hợp lệ

Preset được kiểm tra (validate) phía server theo `KaraokePresetSchema`. SDK export schema này để bạn có thể chuyển nó sang JSON Schema ngay lúc chạy:

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

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

Từ CLI:

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

Tác giả agent nên gọi bước này trước khi chỉnh sửa preset để mô hình biết mọi trường hợp lệ và kiểu giá trị tương ứng.

Tài liệu tham khảo dễ đọc:

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

## Cập nhật một preset

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

Truyền vào bất kỳ tập con nào của `name` và `preset`. Những trường bạn không đưa vào sẽ được giữ nguyên.

## Đặt preset mặc định

Mỗi tài khoản có tối đa một preset mặc định, được tự động áp dụng cho các dự án mới.

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

Khi đặt một mặc định mới, mặc định trước đó sẽ tự động bị bỏ đặt.

## Áp dụng một preset

Tham chiếu một preset ở ba nơi:

| Where                     | Field                                                   |
| ------------------------- | ------------------------------------------------------- |
| Khi tạo dự án             | `presetId` trong `POST /projects`                       |
| Bất kỳ lúc nào trên dự án | `presetId` trong `PATCH /projects/{projectId}/settings` |
| Khi xuất                  | `presetId` trong `POST /projects/{projectId}/exports`   |

Ví dụ khi xuất:

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

## Xoá một preset

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

<Warning>
  Việc xoá một preset không ảnh hưởng đến các dự án hoặc lần xuất đã được render
  với preset đó trước đây. Các lần xuất trong tương lai tham chiếu đến preset đã
  bị xoá sẽ thất bại.
</Warning>

## Tiếp theo

* [Render settings reference](/en/render-settings-reference) — tất cả đường dẫn trường dùng chung và các giá trị enum
* [Media](/vi/api/media) — được tham chiếu từ nội dung preset
* [Project settings](/vi/api/project-settings) — áp dụng một preset cho dự án
* [CLI presets](/vi/cli/presets) — cùng luồng thao tác từ terminal
* [SDK presets](/vi/sdk/presets) — cùng các endpoint trong TypeScript