# @youka/sdk 中文文档

规范地址：https://npmcn.com/package/%40youka/sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-11-02T22:48:42.452Z
中文译文更新时间：2026-11-02T23:38:26.596Z
软件包许可：UNLICENSED

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40youka/sdk
原文对照：https://npmcn.com/package/%40youka/sdk/?lang=original
项目主页：https://docs.youka.io/en/sdk
源码仓库：https://github.com/adam-technology/youka-online

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：946 kB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：4 个
- 首次发布：2026-04-11T22:33:18.736Z
- 最新版本发布：2026-11-02T22:48:42.233Z
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

优卡API的官方Node.js SDK。

## 安装

```sh
npm install @youka/sdk
```

也可以使用：`pnpm add @youka/sdk`、`yarn add @youka/sdk`、`bun add @youka/sdk`

## README

# @youka / sdk

优卡API的官方Node.js SDK。

使用这个包从Node.js创建卡拉ok视频：上传音频或视频，同步或转录歌词，创建卡拉ok项目，渲染最终视频，并下载MP4。

## 安装

```bash
npm install @youka/sdk
```

## API密匙

创建一个API密钥 [online.youka.io /账户](https://online.youka.io/account) 下 **API密钥**.

将密钥保存在源代码之外：

```bash
export YOUKA_API_KEY="yk_..."
```

## 制作卡拉ok视频

```ts
import { AlignmentModel, YoukaClient } from "@youka/sdk";

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

const operation = await client.projects.create({
  source: {
    type: "path",
    path: "./song.mp3",
  },
  lyricsSource: {
    type: "align",
    lyrics: "Line one\nLine two\nLine three",
  },
  title: "Artist - Song",
});

const { project } = await client.projects.wait(operation);

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

const finalized = await client.exports.wait(exportOperation);

await client.exports.download(finalized, {
  output: "./karaoke.mp4",
});
```

## 自动转录歌词

使用转录时，你还没有歌词文本：

```ts
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
  title: "Artist - Song",
});
```

当 `syncModel` 省略时，优卡使用ElevenLabs Scribe。ElevenLabs 每个用户都可以使用转录；AudioShake， MusicAI和Whisper 转录需要付费访问。

## 使用ElevenLabs Scribe

选择ElevenLabs Scribe单词计时转录没有提供的歌词：

```ts
import { AlignmentModel } from "@youka/sdk";

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: {
    type: "transcribe",
    syncModel: AlignmentModel.ElevenLabsTranscription,
  },
  title: "Artist - Song",
});
```

如果你已经有歌词，把它们作为可选的转录指导：

```ts
const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: {
    type: "transcribe",
    syncModel: AlignmentModel.ElevenLabsTranscription,
    lyrics: "Line one\nLine two\nLine three",
  },
  title: "Artist - Song",
});
```

Scribe总是返回自己的单词文本和时间。提供歌词提高词汇识别；它们不会强制输出与提供的文本匹配。

## 使用托管媒体URL

您还可以从托管媒体URL创建卡拉ok视频：

```ts
const operation = await client.projects.create({
  source: {
    type: "url",
    url: "https://example.com/song.mp4",
  },
  lyricsSource: {
    type: "align",
    lyrics: "Line one\nLine two",
  },
});
```

URL帮助程序在第一次使用时自动确保本地下载二进制文件。支持的托管站点依赖于yt-dlp： [https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)

## 处理错误

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

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

  await client.projects.wait(operation);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error(error.code, error.status, error.message);
  } else if (error instanceof YoukaTaskError) {
    console.error(error.code, error.status, error.message);
  } else {
    throw error;
  }
}
```

## 文档

-   Node.js SDK指南： [https://docs.youka.io/en/sdk](https://docs.youka.io/en/sdk)
-   原始HTTP快速入门： [https://docs.youka.io/en/api/quickstart](https://docs.youka.io/en/api/quickstart)
-   CLI指南: [https://docs.youka.io/en/cli](https://docs.youka.io/en/cli)

## 模型发现和歌词视频

使用 `await client.capabilities.get()` 要发现支持的模型、工作流、 输入要求、语言政策和帐户资格。每一个支持 模型表示；隔离声音模型仅限于兼容的工作流。 引用和创建执行相同的规则。

```ts
const operation = await client.projects.create({
  kind: "lyric-video",
  source: { type: "path", path: "./reference.wav" },
  title: "Lyric overlay",
  lyricsSource: {
    type: "transcribe",
    syncModel: AlignmentModel.ElevenLabsTranscription,
    lyrics: "Optional recognition hints",
    languageHintMode: "auto",
  },
});
const { project } = await client.projects.wait(operation);
```

抒情视频跳过分离和拒绝 `splitModel`。省略了 `kind` 保存 卡拉ok的行为。使用 `lyricsSource: { type: "align", lyrics: "...", syncModel }` 用于提供的文本对齐或 `lyricsSource: null` 跳过歌词处理。 `projects.quote()` 接受相同的源/工作流配置。

## 正确的时间安排和重用版本

```ts
const list = await client.projects.alignments.list(project.id);
const current = await client.projects.alignments.get(
  project.id,
  list.alignments[0]!.id,
);
const corrected = structuredClone(current.alignment);
corrected.items[0]!.start = 1.25;
corrected.items[0]!.end = 1.75;
await client.projects.alignments.update(project.id, current.id, {
  alignment: corrected,
  expectedRevision: current.revision,
  select: true,
  expectedSelectionRevision: current.selectionRevision,
});
const versions = await client.projects.versions.list(project.id);
const versionId = versions[0]!.id;
const settings = await client.projects.getSettings(project.id, { versionId });
await client.projects.updateSettings(project.id, {
  versionId,
  settings: settings.settings,
});
const fresh = await client.projects.get(project.id);
await client.exports.create(project.id, {
  target: "local",
  versionId,
  transparent: true,
  stemVolumes: Object.fromEntries(fresh.stems.map((stem) => [stem.id, 0])),
  outputPath: "./overlay.mov",
});
```

计时替换使用完整的、绝对的小数秒计时。保存id, 索引、歌手和翻译元数据。无效的范围被拒绝并且过期 修订返回冲突；重试前请重新获取并调和。选择独自一人 使用 `projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision })`。这两个操作都不会启动AI任务。

本地透明导出使用ProRes 4444。静音茎意味着静音输出；它 不承诺删除音频流。本地出口开始没有付费渲染 或重新调整工作，并保留现有的功能资格。行期待 layout-dependent;它不是固定的每行显示保证。

这些方法要求在实例之前部署匹配的服务器端点 发布SDK新版本。参见存储库的capability-parity指南 推出和验收需求。

## 常见问题

### @youka/sdk 是什么？

优卡API的官方Node\.js SDK。

### 如何安装 @youka/sdk？

在项目目录运行 npm install @youka/sdk，或使用 pnpm add / yarn add / bun add。

### @youka/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @youka/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @youka/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @youka/sdk 可以商用吗？

@youka/sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @youka/sdk 还在维护吗？

最新版本 0\.3\.0 发布于 2026/11/03（今天）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/04/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。