> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Steps>
  <Step title="Create an upload target">
    ```bash theme={null}
    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`.
  </Step>

  <Step title="PUT the file bytes">
    ```bash theme={null}
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: video/mp4" \
      --data-binary "@./background.mp4"
    ```
  </Step>

  <Step title="Register the media item">
    ```bash theme={null}
    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.
  </Step>
</Steps>

<Note>
  `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 đó.
</Note>

## Liệt kê media

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
curl -X DELETE https://api.youka.io/vi/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"
```

<Warning>
  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.
</Warning>

## Tiếp theo

* [Render settings reference](/en/render-settings-reference) — tất cả đường dẫn field dùng chung và các giá trị enum
* [Presets](/vi/api/presets) — gói media cùng các cài đặt render khác
* [Project settings](/vi/api/project-settings) — áp dụng nền cho một dự án
* [SDK media](/vi/sdk/media) — cùng một luồng trong TypeScript