Projects

Projects 是 Youka 中的顶层资源。每个项目都拥有其源文件、歌词、导出内容以及项目设置。卡拉 OK 项目还包含分离后的音轨（stems）。

创建项目

大多数情况下，使用 client.projects.create() ——它会为你处理上传。

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

Source 类型

path
bytes
url

从磁盘读取文件。

source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

内存中的 Blob、File、ArrayBuffer 或 Uint8Array。

source: {
  type: "bytes",
  data: fileBuffer,
  filename: "song.mp3",
  contentType: "audio/mpeg", // optional
}

远程 HTTP 或 HTTPS URL。支持的托管页面取决于 yt-dlp。请参阅 supported URLs list。

source: {
  type: "url",
  url: "https://example.com/song.mp4",
  maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}

maxVideoQuality 控制 URL source 下载的视频最高画质。默认值为 1080p。SDK 会使用不超过该上限的最佳可用画质；如果平台未提供带上限的流，则会回退到最佳可用格式。使用 best 表示不设上限。

在 Node.js 和 Bun 中，SDK 会在首次使用时自动确保所需的 URL 依赖二进制文件（ffmpeg、ffprobe、yt-dlp）。对应的 CLI 命令是 youka deps ensure --for url。

其他字段

string

项目标题。默认为源文件名。

karaoke | lyric-video

工作流。默认为 karaoke。lyric-video 使用原始音频，不进行音轨分离。

SplitModel

用于 karaoke 的音轨分离模型。默认为 mdx23c。在 lyric-video 中会被拒绝。参见 Split model reference。

string

在创建时应用一个可复用的预设。

LyricsSource

配置歌词同步。见下文。

Lyrics sources

// Transcribe lyrics from the audio
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// Align exact lyrics to the audio
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

`client.projects.create(input, options?)`

当你已经有上传后的 inputFileId 时，client.projects.create() 也接受更底层的 inputFile source。

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: buffer.byteLength,
});

await client.uploads.upload(upload.uploadUrl, buffer, {
  contentType: "audio/mpeg",
});

const operation = await client.projects.create({
  source: {
    type: "inputFile",
    inputFileId: upload.inputFileId,
    filename: "song.mp3",
  },
  title: "My Song",
});

`client.projects.quote(input, options?)`

在不创建项目的情况下，预估创建项目所需的 credits。

const quote = await client.projects.quote({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe", language: "en" },
  splitModel: "mdx23c",
});

console.log(quote.creditsRequired, quote.sufficientBalance);

client.projects.quote(...) 接受与 client.projects.create(...) 相同的 source 形式，包括 URL 的 maxVideoQuality。如果你已经知道媒体时长，并且不想为了 quote 而上传文件，请传入更底层的 REST 形状：

const quote = await client.projects.quote({
  durationSeconds: 210,
  lyricsSource: null,
  splitModel: "mdx23c",
});

`client.uploads.create(body, options?)`

分配一个上传槽位并获取签名 URL。

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }

`client.uploads.upload(uploadUrl, body, options?)`

使用 PUT 将文件字节上传到签名 URL。

await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});

FetchBody

required

任何与 fetch 兼容的 body：Blob、File、ArrayBuffer、Uint8Array、ReadableStream 或 string。

如果上传返回非 2xx 状态，会抛出 code 为 UPLOAD_FAILED 的 YoukaRequestError。

`client.projects.get(projectId, options?)`

获取完整的项目状态，包括 stems、歌词和导出内容。

const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);

`client.projects.update(projectId, body, options?)`

更新项目元数据（patch）。

const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});

至少传入 title 或 artists 之一。

`client.projects.list(options?)`

列出已认证账号所拥有的所有项目。

const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));

返回一个项目列表项数组（形状比 getProject 更精简）。

`client.projects.delete(projectId, options?)`

删除项目及其关联的所有 stems、歌词和导出内容。

await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});

删除是永久性的。请配合幂等键使用，以确保重试安全。

下一步

Stems — 重新运行音轨分离
Lyrics sync — 重新同步歌词
Exports — 渲染成品视频
Tasks — 使用 client.projects.wait 等待项目操作完成

创建 Lyric-video 与模型发现

const capabilities = await client.capabilities.get();
const operation = await client.projects.create({
  kind: "lyric-video",
  source: { type: "path", path: "./song.wav" },
  lyricsSource: {
    type: "transcribe",
    syncModel: "elevenlabs-transcription",
    lyrics: "Optional reference lyrics",
  },
});
const { project } = await client.projects.wait(operation);
const versions = await client.projects.versions.list(project.id);

相同的 kind 与歌词处理选项也适用于 projects.quote。Lyric-video 的 quote 不收取分离 credits。Quote 与 create 会验证相同的模型、语言、账号与 source 要求。Quote 不会预留 credits 或容量。使用 lyricsSource: null 跳过歌词处理。转录中的参考文本仅用于引导，可能与结果不同。需要人声分离的模型无法处理不分离的 lyric video。关于 capabilities、精确时间轴更新与目录检查点，请参阅 Automate lyric videos。

Overview

How To

Customization

Audio

Settings

Exporting

Account

创建项目

Source 类型

其他字段

Lyrics sources

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

下一步

创建 Lyric-video 与模型发现

​创建项目

​Source 类型

​其他字段

​Lyrics sources

​client.projects.create(input, options?)

​client.projects.quote(input, options?)

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

​client.uploads.upload(uploadUrl, body, options?)

​client.projects.get(projectId, options?)

​client.projects.update(projectId, body, options?)

​client.projects.list(options?)

​client.projects.delete(projectId, options?)

​下一步

​创建 Lyric-video 与模型发现

创建项目

Source 类型

其他字段

Lyrics sources

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

下一步

创建 Lyric-video 与模型发现