Skip to main content
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

MethodPathPurpose
GET/presetsLiệt kê preset cho tài khoản đã xác thực.
POST/presetsTạ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:
WhereField
Khi tạo dự ánpresetId trong POST /projects
Bất kỳ lúc nào trên dự ánpresetId trong PATCH /projects/{projectId}/settings
Khi xuấtpresetId 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.

​
Tiếp theo