Quickstart - Youka Docs

This guide walks through the fastest path from a raw audio file to a rendered karaoke video using @youka/sdk.

Before you start

Node.js 20 or later
A Youka API key in YOUKA_API_KEY (create one at online.youka.io/account under API keys)
A local audio file (./song.mp3) or a remote URL

Install

npm install @youka/sdk

Create, wait, export

import { YoukaClient, YoukaRequestError, YoukaTaskError } from "@youka/sdk";

const client = new YoukaClient({
  apiKey: process.env.YOUKA_API_KEY!,
});

async function main() {
  // 1. Create a project from a local file
  const projectOperation = await client.projects.create({
    source: { type: "path", path: "./song.mp3" },
    lyricsSource: { type: "transcribe" },
  });

  // 2. Wait for stems and lyrics sync to finish
  const { project } = await client.projects.wait(projectOperation);
  console.log("Project ready:", project.id, project.title);

  // 3. Start an export
  const exportOperation = await client.exports.create(project.id, {
    resolution: "1080p",
    quality: "high",
  });

  // 4. Wait for the export to finish
  const finishedExport = await client.exports.wait(exportOperation);
  await client.exports.download(finishedExport, {
    output: "./exports",
  });
  console.log("Export ready:", finishedExport.url);
}

main().catch((error) => {
  if (error instanceof YoukaRequestError) {
    console.error("Request failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  if (error instanceof YoukaTaskError) {
    console.error("Task failed:", error.code, error.status, error.message);
    process.exit(1);
  }
  throw error;
});

client.projects.create() handles uploads for path, bytes, and url sources. For lower-level upload control, use client.uploads.*.

Three source types

Local file
In-memory bytes
Remote URL

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
});

const fileBuffer = new Uint8Array([/* audio bytes */]);

const operation = await client.projects.create({
  source: {
    type: "bytes",
    data: fileBuffer,
    filename: "song.mp3",
  },
});

const operation = await client.projects.create({
  source: {
    type: "url",
    url: "https://example.com/song.mp4",
  },
});

What’s next

Projects — full projects API
Exports — local render and client.exports.prepareLocal
Errors — handle YoukaRequestError and YoukaTaskError
AI agents — recommended polling and retry patterns