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

​
媒体类型

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

​
client.media.list(options?)

列出已认证账号拥有的所有可复用媒体项。 
const media = await client.media.list();

​
client.media.get(mediaId, options?)

获取单个媒体项。 
const media = await client.media.get("bg_abc123");

​
client.media.create(body, options?)

从本地路径、字节数据或已上传的 inputFileId 创建新的媒体项。对于本地路径和字节数据，SDK 会准备上传、将文件字节发送到上传 URL，并把已上传文件注册为可复用媒体。 
const media = await client.media.create({
  type: "video",
  source: {
    type: "path",
    path: "./background.mp4",
    contentType: "video/mp4",
  },
});
​
type
'video' | 'image' | 'logo' | 'intro-video' | 'outro-video'
required
该媒体项在渲染中承担的角色。
​
source
object
文件来源。本地文件使用 { type: "path", path }；Blob、File、ArrayBuffer 或类型化数组数据使用 { type: "bytes", data, filename }；当你已经有上传 ID 时，使用 { type: "inputFile", inputFileId }。
​
inputFileId
string
高级底层选项：传入 client.uploads.create(...) 返回的 ID 来代替 source。

​
client.media.delete(mediaId, options?)

删除一个媒体项。 
await client.media.delete("bg_abc123", {
  idempotencyKey: "delete-bg_abc123",
});
删除媒体不会影响此前使用该媒体渲染过的项目或导出内容。未来引用已删除媒体的渲染将回退到默认背景。

​
端到端示例

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);

​
应用背景

从预设中引用已上传媒体，或直接在项目设置中引用： 
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： 
import { RestUpdateProjectSettingsRequestSchema } from "@youka/sdk";

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();

​
接下来