Skip to main content
Media are reusable files — video backgrounds, static images, logos, and intro/outro clips — that you can reference from presets or project settings. Upload once and reuse across projects.

​
Media types

TypeDescription
videoLooping background video.
imageStatic background image.
logoLogo overlay.
intro-videoPlays before the karaoke starts.
outro-videoPlays after the karaoke ends.

​
client.media.list(options?)

List every reusable media item owned by the authenticated account. 
const media = await client.media.list();

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

Fetch a single media item. 
const media = await client.media.get("bg_abc123");

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

Create a new media item from a local path, bytes, or an existing uploaded inputFileId. For local paths and bytes, the SDK prepares the upload, sends the file bytes to the upload URL, and registers the uploaded file as reusable media. 
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
Which role this media item fills in a render.
​
source
object
The file source. Use { type: "path", path } for local files, { type: "bytes", data, filename } for Blob, File, ArrayBuffer, or typed array data, or { type: "inputFile", inputFileId } when you already have an upload ID.
​
inputFileId
string
Advanced low-level option: pass the ID returned by client.uploads.create(...) instead of source.

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

Delete a media item. 
await client.media.delete("bg_abc123", {
  idempotencyKey: "delete-bg_abc123",
});
Deleting media does not affect projects or exports that were previously rendered with it. Future renders that reference the deleted media will fall back to the default background.

​
End-to-end example

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

​
Applying a background

Reference uploaded media from a preset or directly from project settings: 
const media = await uploadBackground("./loop.mp4", "video/mp4");

await client.projects.updateSettings("prj_abc123", {
  settings: {
    style: {
      background: {
        type: "video",
        url: media.url,
        objectFit: "cover",
      },
    },
  },
});
For the full set of fields accepted under background, convert the project settings schema to JSON: 
import { RestUpdateProjectSettingsRequestSchema } from "@youka/sdk";

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();

​
What’s next