Preset

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 để 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

Dùng preset khi…

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.

Dùng cài đặt dự án khi…

Bạn cần các ghi đè riêng cho từng dự án và không đáng để chia sẻ.

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

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.

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.

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:

import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();

Từ CLI:

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:

Cập nhật một preset

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.

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:

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

curl -X DELETE https://api.youka.io/vi/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"

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.

Render settings reference — tất cả đường dẫn trường dùng chung và các giá trị enum
Media — được tham chiếu từ nội dung preset
Project settings — áp dụng một preset cho dự án
CLI presets — cùng luồng thao tác từ terminal
SDK presets — cùng các endpoint trong TypeScript

Overview

How To

Customization

Audio

Settings

Exporting

Account

Khi nào nên dùng preset

Dùng preset khi…

Dùng cài đặt dự án khi…

Endpoints

Tạo một preset

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

Cập nhật một preset

Đặt preset mặc định

Áp dụng một preset

Xoá một preset

Tiếp theo

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

Dùng preset khi…

Dùng cài đặt dự án khi…

​Endpoints

​Tạo một preset

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

​Cập nhật một preset

​Đặt preset mặc định

​Áp dụng một preset

​Xoá một preset

​Tiếp theo

Khi nào nên dùng preset

Endpoints

Tạo một preset

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

Cập nhật một preset

Đặt preset mặc định

Áp dụng một preset

Xoá một preset

Tiếp theo