미디어

미디어는 재사용 가능한 파일(비디오 배경, 정적 이미지, 로고, 인트로/아웃트로 클립)로, 한 번 업로드한 뒤 프리셋이나 프로젝트 설정에서 참조해 사용할 수 있습니다. 이렇게 하면 새 트랙을 렌더링할 때마다 같은 파일을 다시 업로드할 필요가 없습니다.

미디어 유형

유형	설명
`video`	반복 재생되는 배경 비디오.
`image`	정적 배경 이미지.
`logo`	로고 오버레이.
`intro-video`	카라오케가 시작되기 전에 재생됨.
`outro-video`	카라오케가 끝난 뒤에 재생됨.

엔드포인트

Method	Path	목적
`GET`	`/media`	인증된 계정의 미디어 목록을 조회합니다.
`POST`	`/media`	이전에 업로드한 파일을 재사용 가능한 미디어로 등록합니다.
`GET`	`/media/{mediaId}`	단일 미디어 항목을 가져옵니다.
`DELETE`	`/media/{mediaId}`	미디어 항목을 삭제합니다.

전체 요청 및 응답 스키마는 API reference에 있습니다.

업로드 흐름

미디어 항목 생성은 2단계로 진행됩니다. 먼저 파일 바이트를 업로드한 다음, 업로드된 파일을 재사용 가능한 미디어로 등록합니다.

업로드 대상 생성

curl -X POST https://api.youka.io/ko/api/v1/uploads \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "background.mp4",
    "contentType": "video/mp4",
    "contentLength": 8421120
  }'

응답에는 inputFileId와 uploadUrl이 포함됩니다.

파일 바이트 PUT

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./background.mp4"

미디어 항목 등록

curl -X POST https://api.youka.io/ko/api/v1/media \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: bg-loop-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "inputFileId": "file_abc123",
    "type": "video"
  }'

응답에는 새 mediaId와 미디어 url이 포함됩니다. 프리셋이나 프로젝트 설정에서 url을 사용하세요.

POST /media는 원시 파일 업로드를 받지 않습니다. 이전 POST /uploads + PUT 호출에서 받은 inputFileId를 기대합니다.

미디어 목록 조회

curl https://api.youka.io/ko/api/v1/media \
  -H "Authorization: Bearer yk_..."

인증된 계정에 있는 모든 재사용 가능한 미디어 항목의 배열을 반환합니다.

배경 적용

프리셋에서 또는 프로젝트 설정에서 직접 업로드된 미디어를 참조하세요:

curl -X PATCH https://api.youka.io/ko/api/v1/projects/prj_abc/settings \
  -H "Authorization: Bearer yk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "style": {
        "background": {
          "type": "image",
          "url": "https://cdn.youka.io/backgrounds/bg_abc123.jpg",
          "objectFit": "cover"
        }
      }
    }
  }'

미디어 삭제

curl -X DELETE https://api.youka.io/ko/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"

미디어를 삭제해도 이를 사용해 이전에 렌더링된 프로젝트나 내보내기 결과에는 영향을 주지 않습니다. 삭제된 미디어를 참조하는 향후 렌더링은 기본 배경으로 대체됩니다.

다음 단계

Render settings reference — 모든 공통 필드 경로와 enum 값
Presets — 다른 렌더 설정과 함께 미디어를 묶기
Project settings — 프로젝트에 배경 적용
SDK media — TypeScript에서의 동일한 흐름

Overview

How To

Customization

Audio

Settings

Exporting

Account

미디어 유형

엔드포인트

업로드 흐름

미디어 목록 조회

배경 적용

미디어 삭제

다음 단계

​미디어 유형

​엔드포인트

​업로드 흐름

​미디어 목록 조회

​배경 적용

​미디어 삭제

​다음 단계

미디어 유형

엔드포인트

업로드 흐름

미디어 목록 조회

배경 적용

미디어 삭제

다음 단계