媒体 - Youka Docs

媒体是可复用的文件——视频背景、静态图片、Logo，以及片头/片尾片段——你只需上传一次，然后即可在预设或项目设置中引用它们。这样可以避免每次渲染新曲目时都重复上传同一个文件。

媒体类型

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

端点

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

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

上传流程

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

创建上传目标

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。

PUT 文件字节

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary "@./background.mp4"

注册媒体条目

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。

POST /media 不接受原始文件上传。它需要来自先前 POST /uploads + PUT 调用的 inputFileId。

列出媒体

curl https://api.youka.io/zh/api/v1/media \
  -H "Authorization: Bearer yk_..."

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

应用背景

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

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"
        }
      }
    }
  }'

删除媒体

curl -X DELETE https://api.youka.io/zh/api/v1/media/bg_abc123 \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: delete-bg_abc123"

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

下一步

Render settings reference — 所有共享字段路径与枚举值
Presets — 将媒体与其他渲染设置打包
Project settings — 为项目应用背景
SDK media — TypeScript 中的同一流程

Overview

How To

Customization

Audio

Settings

Exporting

Account

媒体

媒体类型

端点

上传流程

列出媒体

应用背景

删除媒体

下一步

​媒体类型

​端点

​上传流程

​列出媒体

​应用背景

​删除媒体

​下一步

媒体类型

端点

上传流程

列出媒体

应用背景

删除媒体

下一步