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

# 미디어

> 재사용 가능한 배경, 로고, 인트로/아웃트로 비디오

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

## 미디어 유형

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

## 엔드포인트

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

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

## 업로드 흐름

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

<Steps>
  <Step title="업로드 대상 생성">
    ```bash theme={null}
    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`이 포함됩니다.
  </Step>

  <Step title="파일 바이트 PUT">
    ```bash theme={null}
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: video/mp4" \
      --data-binary "@./background.mp4"
    ```
  </Step>

  <Step title="미디어 항목 등록">
    ```bash theme={null}
    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`을 사용하세요.
  </Step>
</Steps>

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

## 미디어 목록 조회

```bash theme={null}
curl https://api.youka.io/ko/api/v1/media \
  -H "Authorization: Bearer yk_..."
```

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

## 배경 적용

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

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

## 미디어 삭제

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

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

## 다음 단계

* [Render settings reference](/en/render-settings-reference) — 모든 공통 필드 경로와 enum 값
* [Presets](/ko/api/presets) — 다른 렌더 설정과 함께 미디어를 묶기
* [Project settings](/ko/api/project-settings) — 프로젝트에 배경 적용
* [SDK media](/ko/sdk/media) — TypeScript에서의 동일한 흐름