미디어는 재사용 가능한 파일(비디오 배경, 정적 이미지, 로고, 인트로/아웃트로 클립)로, 한 번 업로드한 뒤 프리셋이나 프로젝트 설정에서 참조해 사용할 수 있습니다. 이렇게 하면 새 트랙을 렌더링할 때마다 같은 파일을 다시 업로드할 필요가 없습니다.
미디어 유형
| 유형 | 설명 |
|---|
video | 반복 재생되는 배경 비디오. |
image | 정적 배경 이미지. |
logo | 로고 오버레이. |
intro-video | 카라오케가 시작되기 전에 재생됨. |
outro-video | 카라오케가 끝난 뒤에 재생됨. |
엔드포인트
| Method | Path | 목적 |
|---|
GET | /media | 인증된 계정의 미디어 목록을 조회합니다. |
POST | /media | 이전에 업로드한 파일을 재사용 가능한 미디어로 등록합니다. |
GET | /media/{mediaId} | 단일 미디어 항목을 가져옵니다. |
DELETE | /media/{mediaId} | 미디어 항목을 삭제합니다. |
업로드 흐름
미디어 항목 생성은 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"
미디어를 삭제해도 이를 사용해 이전에 렌더링된 프로젝트나 내보내기 결과에는 영향을 주지 않습니다.
삭제된 미디어를 참조하는 향후 렌더링은 기본 배경으로 대체됩니다.
다음 단계
