> ## 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 结束后播放。 |

## 端点

| 方法       | 路径                 | 用途                |
| -------- | ------------------ | ----------------- |
| `GET`    | `/media`           | 列出已认证账号下的媒体。      |
| `POST`   | `/media`           | 将先前上传的文件注册为可复用媒体。 |
| `GET`    | `/media/{mediaId}` | 获取单个媒体条目。         |
| `DELETE` | `/media/{mediaId}` | 删除媒体条目。           |

完整的请求与响应 schema 请参见 **API reference**。

## 上传流程

创建媒体条目是一个两步流程。先上传文件字节，再把已上传的文件注册为可复用媒体。

<Steps>
  <Step title="创建上传目标">
    ```bash theme={null}
    curl -X POST https://api.youka.io/zh/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/zh/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/zh/api/v1/media \
  -H "Authorization: Bearer yk_..."
```

返回已认证账号下所有可复用媒体条目的数组。

## 应用背景

从预设中引用已上传媒体，或直接在项目设置中引用：

```bash theme={null}
curl -X PATCH https://api.youka.io/zh/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/zh/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"
```

<Warning>
  删除媒体不会影响之前使用它渲染的项目或导出结果。未来引用已删除媒体的渲染将回退到默认背景。
</Warning>

## 下一步

* [Render settings reference](/en/render-settings-reference) — 所有共享字段路径与枚举值
* [Presets](/zh/api/presets) — 将媒体与其他渲染设置打包
* [Project settings](/zh/api/project-settings) — 为项目应用背景
* [SDK media](/zh/sdk/media) — TypeScript 中的同一流程