Skip to main content
프리셋은 어떤 프로젝트나 내보내기에 적용할 수 있는 재사용 가능한 렌더 구성(배경, 자막 스타일, 레이아웃 등)입니다. 여러 트랙에서 일관된 룩을 유지해야 할 때 프리셋을 사용하세요. 전체 preset 형태와 enum 기반의 모든 옵션은 Render settings reference에서 확인할 수 있습니다.

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

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

여러 프로젝트에서 동일한 룩이 필요하고, 한 곳에서 업데이트하고 싶을 때.

프로젝트 설정을 사용해야 하는 경우…

공유할 가치가 없는 프로젝트 로컬 오버라이드가 필요할 때.

​
엔드포인트

MethodPathPurpose
GET/presets인증된 계정의 프리셋 목록을 조회합니다.
POST/presets새 프리셋을 생성합니다.
GET/presets/{presetId}단일 프리셋을 가져옵니다.
PATCH/presets/{presetId}이름/본문을 업데이트하거나 기본값으로 설정합니다.
DELETE/presets/{presetId}프리셋을 삭제합니다.
전체 요청 및 응답 스키마는 사이드바의 API reference에서 확인할 수 있습니다.

​
프리셋 생성

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가 포함됩니다. 이를 저장해 두고 프로젝트 또는 내보내기에서 참조하세요.
모든 POST에 멱등성 키를 함께 사용하세요. 동일한 키를 동일한 payload와 함께 재사용하면 중복을 생성하는 대신 기존 프리셋을 반환합니다.

​
유효한 프리셋 필드 확인

프리셋은 서버 측에서 KaraokePresetSchema에 대해 검증됩니다. SDK는 이 스키마를 내보내므로 런타임에 JSON Schema로 변환할 수 있습니다: 
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
CLI에서: 
youka preset schema --json
에이전트 작성자는 프리셋을 변경하기 전에 이를 호출해 모델이 모든 유효한 필드와 값 타입을 알 수 있게 해야 합니다. 사람이 읽기 쉬운 참고 자료:

​
프리셋 업데이트

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개까지 있으며, 새 프로젝트에 자동으로 적용됩니다. 
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
  }'
새 기본값을 설정하면 이전 기본값은 자동으로 해제됩니다.

​
프리셋 적용

프리셋은 다음 세 곳에서 참조할 수 있습니다:
WhereField
프로젝트 생성 시POST /projects의 presetId
프로젝트에서 언제든지PATCH /projects/{projectId}/settings의 presetId
내보내기 시POST /projects/{projectId}/exports의 presetId
내보내기 예시: 
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"
  }'

​
프리셋 삭제

curl -X DELETE https://api.youka.io/ko/api/v1/presets/preset_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-preset_abc123"
프리셋을 삭제해도 이전에 해당 프리셋으로 렌더링된 프로젝트나 내보내기에는 영향이 없습니다. 삭제된 프리셋을 참조하는 향후 내보내기는 실패합니다.

​
다음 단계