Media

Nền, logo và video intro/outro có thể tái sử dụng

Media là các tệp có thể tái sử dụng — nền video, hình ảnh tĩnh, logo, và các đoạn intro/outro — bạn tải lên một lần và tham chiếu từ preset hoặc cài đặt dự án. Điều này giúp bạn không phải tải lại cùng một tệp mỗi lần render một track mới.

Các loại media

Type	Description
video	Video nền lặp (loop).
image	Hình nền tĩnh.
logo	Lớp phủ logo.
intro-video	Phát trước khi karaoke bắt đầu.
outro-video	Phát sau khi karaoke kết thúc.

Endpoints

Method	Path	Purpose
GET	/media	Liệt kê media cho tài khoản đã xác thực.
POST	/media	Đăng ký một tệp đã tải lên trước đó thành media tái sử dụng.
GET	/media/{mediaId}	Lấy một mục media đơn.
DELETE	/media/{mediaId}	Xóa một mục media.

Schema đầy đủ của request và response nằm trong API reference.

Luồng upload

Tạo một media item là quy trình gồm hai bước. Trước tiên upload dữ liệu tệp (bytes), sau đó đăng ký tệp đã upload thành media tái sử dụng.

1. Create an upload target

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

   Response chứa inputFileId và uploadUrl.

2. PUT the file bytes

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

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

   Response bao gồm mediaId mới và url của media. Dùng url bên trong preset hoặc cài đặt dự án.

POST /media không chấp nhận upload tệp thô. Endpoint này yêu cầu một inputFileId từ lần gọi POST /uploads + PUT trước đó.

Liệt kê media

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

Trả về một mảng gồm mọi media item có thể tái sử dụng trên tài khoản đã xác thực.

Áp dụng nền

Tham chiếu media đã upload từ preset hoặc trực tiếp từ cài đặt dự án:

curl -X PATCH https://api.youka.io/vi/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"
        }
      }
    }
  }'

Xóa media

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

Việc xóa media không ảnh hưởng đến các dự án hoặc bản export đã được render trước đó với media này. Các lần render trong tương lai tham chiếu đến media đã xóa sẽ tự động quay về nền mặc định.

Tiếp theo

• Render settings reference — tất cả đường dẫn field dùng chung và các giá trị enum
• Presets — gói media cùng các cài đặt render khác
• Project settings — áp dụng nền cho một dự án
• SDK media — cùng một luồng trong TypeScript