> ## 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` | 노래방이 끝난 후에 재생됨.   |

## `client.media.list(options?)`

인증된 계정이 소유한 모든 재사용 미디어 항목을 나열합니다.

```ts theme={null}
const media = await client.media.list();
```

## `client.media.get(mediaId, options?)`

단일 미디어 항목을 가져옵니다.

```ts theme={null}
const media = await client.media.get("bg_abc123");
```

## `client.media.create(body, options?)`

로컬 경로, 바이트, 또는 이미 업로드된 `inputFileId`로 새 미디어 항목을 생성합니다. 로컬 경로와 바이트의 경우 SDK가 업로드를 준비하고, 업로드 URL로 파일 바이트를 전송한 다음, 업로드된 파일을 재사용 가능한 미디어로 등록합니다.

```ts theme={null}
const media = await client.media.create({
  type: "video",
  source: {
    type: "path",
    path: "./background.mp4",
    contentType: "video/mp4",
  },
});
```

<ParamField path="type" type="'video' | 'image' | 'logo' | 'intro-video' | 'outro-video'" required>
  이 미디어 항목이 렌더링에서 담당하는 역할입니다.
</ParamField>

<ParamField path="source" type="object">
  파일 소스입니다. 로컬 파일에는 `{ type: "path", path }`를, `Blob`, `File`, `ArrayBuffer` 또는 typed array 데이터에는 `{ type:
      "bytes", data, filename }`를, 이미 업로드 ID가 있는 경우에는 `{ type: "inputFile", inputFileId }`를 사용하세요.
</ParamField>

<ParamField path="inputFileId" type="string">
  고급 로우레벨 옵션: `source` 대신 `client.uploads.create(...)`가 반환한 ID를 전달합니다.
</ParamField>

## `client.media.delete(mediaId, options?)`

미디어 항목을 삭제합니다.

```ts theme={null}
await client.media.delete("bg_abc123", {
  idempotencyKey: "delete-bg_abc123",
});
```

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

## 엔드-투-엔드 예제

```ts theme={null}
import { YoukaClient } from "@youka/sdk";

const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });

async function uploadBackground(path: string, contentType: string) {
  return client.media.create({
    type: "video",
    source: {
      type: "path",
      path,
      contentType,
    },
  });
}

const media = await uploadBackground("./loop.mp4", "video/mp4");
console.log("Media ID:", media.id);
```

## 배경 적용하기

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

```ts theme={null}
const media = await uploadBackground("./loop.mp4", "video/mp4");

await client.projects.updateSettings("prj_abc123", {
  settings: {
    style: {
      background: {
        type: "video",
        url: media.url,
        objectFit: "cover",
      },
    },
  },
});
```

`background` 아래에서 허용되는 전체 필드 집합을 보려면, 프로젝트 설정 스키마를 JSON으로 변환하세요:

```ts theme={null}
import { RestUpdateProjectSettingsRequestSchema } from "@youka/sdk";

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();
```

## 다음 단계

* [렌더 설정 레퍼런스](/en/render-settings-reference) — 모든 공용 필드 경로와 enum 값
* [프로젝트](/ko/sdk/projects) — 프로젝트 생성 및 업로드
* [프리셋](/ko/sdk/presets) — 다른 렌더 설정과 함께 미디어를 번들링
* [프로젝트 설정](/ko/sdk/project-settings) — 프로젝트에 배경 적용하기