Youka CLI - Youka Docs

Youka CLI 封装了公共 API，因此你可以从歌曲创建卡拉 OK，自定义歌词和视频样式，并通过终端或 agent 导出成品 MP4。

安装

npm install -g @youka/cli

pnpm add -g @youka/cli

yarn global add @youka/cli

验证安装：

youka --version
youka --help

设置认证

获取 API key

前往 online.youka.io/account，打开 API keys，并复制一个新的 key。

保存 key

将 key 持久化保存到 ~/.youka/config.json：

youka login YOUR_API_KEY

或将其导出为环境变量：

export YOUKA_API_KEY=YOUR_API_KEY

从文件创建卡拉 OK

使用本地音频或视频文件作为源：

youka project create ./song.mp3 --download --output ./karaoke.mp4 --wait --json

该命令会上传源文件、创建卡拉 OK 项目、渲染导出，并下载最终的 MP4 视频。

从 URL 创建卡拉 OK

传入 HTTP 或 HTTPS 源 URL 来替代文件路径：

youka project create "https://example.com/song.mp4" --download --output ./karaoke.mp4 --wait --json

对于托管的视频 URL，Youka 使用 yt-dlp 从该 URL 下载。你可以在第一次通过 URL 导入之前安装 URL 下载依赖：

youka deps ensure --for url

参考

账户

点数

查看当前余额和即将过期的点数套餐。

计费

显示定价并创建结账或门户 URL。

项目

创建、查看、等待并更新项目。

导出

渲染云端或本地导出产物并下载。

预设

管理可复用的渲染配置。

媒体

上传并管理可复用媒体资源。

任务

需要时检查底层任务状态。

依赖

检查并安装 URL 导入和本地渲染依赖。

全局选项

每个命令都可用的标志。

默认即可供 agent 使用

每个命令都支持机器可读模式，返回一个结构稳定的单一 JSON 信封。使用这些标志可从 agent 或脚本驱动 CLI：

标志	用途
`--json`	向 stdout 仅输出一个 JSON 信封。进度与日志将被抑制。
`--body <file\|->`	从文件或 stdin 合并 JSON payload。CLI 标志会覆盖同名字段。
`--wait`	轮询异步任务（project create、exports），直到进入终止状态。
`--idempotency-key <key>`	向任何写入操作传入幂等 key。
`--quiet`	与 `--wait` 一起使用时，抑制非 JSON 的进度输出。
`--api <url>`	覆盖公共 API 的 base URL。

JSON 信封结构：

{
  "ok": true,
  "data": {
    /* command result */
  }
}

失败时：

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Human-readable description",
    "details": {
      /* optional */
    }
  }
}

完整列表请参见全局选项。

云端 vs 本地导出

export create 默认在云端运行。传入 --local 可使用随附的 Remotion 工具链在你的机器上渲染。本地渲染需要安装渲染依赖：

youka deps ensure --for render

完整工作流请参见导出。

下一步

账户 - 保存你的 API key
项目 - 创建并处理项目
导出 - 渲染最终的卡拉 OK 视频
AI agents - 在自动化工作流中驱动 CLI

​安装

​设置认证

​从文件创建卡拉 OK

​从 URL 创建卡拉 OK

​参考

账户

点数

计费

项目

导出

预设

媒体

任务

依赖

全局选项

​默认即可供 agent 使用

​云端 vs 本地导出

​下一步

安装

设置认证

从文件创建卡拉 OK

从 URL 创建卡拉 OK

参考

默认即可供 agent 使用

云端 vs 本地导出

下一步