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

# 媒体

> 上传并管理可复用的背景、Logo 以及片头/片尾视频

媒体是可复用的文件——视频背景、静态图片、Logo，以及片头/片尾片段——你可以在预设或项目设置中引用它们。上传一次，即可跨项目重复使用。

## 媒体类型

| 类型            | 描述            |
| ------------- | ------------- |
| `video`       | 循环播放的背景视频。    |
| `image`       | 静态背景图片。       |
| `logo`        | Logo 叠加层。     |
| `intro-video` | 在卡拉 OK 开始前播放。 |
| `outro-video` | 在卡拉 OK 结束后播放。 |

## `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` 或类型化数组数据使用 `{ type:
      "bytes", data, filename }`；当你已经有上传 ID 时，使用 `{ type: "inputFile", inputFileId }`。
</ParamField>

<ParamField path="inputFileId" type="string">
  高级底层选项：传入 `client.uploads.create(...)` 返回的 ID 来代替 `source`。
</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` 下可接受的完整字段集合，请将项目设置 schema 转换为 JSON：

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

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

## 接下来

* [渲染设置参考](/en/render-settings-reference) — 所有共享字段路径与枚举值
* [Projects](/zh/sdk/projects) — 项目创建与上传
* [Presets](/zh/sdk/presets) — 将媒体与其他渲染设置打包
* [Project settings](/zh/sdk/project-settings) — 将背景应用到项目中