> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Youka CLI

> 通过命令行创建卡拉 OK、自定义样式，并导出 MP4 视频

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

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @youka/cli
  ```

  ```bash pnpm theme={null}
  pnpm add -g @youka/cli
  ```

  ```bash yarn theme={null}
  yarn global add @youka/cli
  ```
</CodeGroup>

验证安装：

```bash theme={null}
youka --version
youka --help
```

## 设置认证

<Steps>
  <Step title="获取 API key">
    前往 [online.youka.io/account](https://online.youka.io/account)，打开
    **API keys**，并复制一个新的 key。
  </Step>

  <Step title="保存 key">
    将 key 持久化保存到 `~/.youka/config.json`：

    ```bash theme={null}
    youka login YOUR_API_KEY
    ```

    或将其导出为环境变量：

    ```bash theme={null}
    export YOUKA_API_KEY=YOUR_API_KEY
    ```
  </Step>
</Steps>

## 从文件创建卡拉 OK

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

```bash theme={null}
youka project create ./song.mp3 --download --output ./karaoke.mp4 --wait --json
```

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

## 从 URL 创建卡拉 OK

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

```bash theme={null}
youka project create "https://example.com/song.mp4" --download --output ./karaoke.mp4 --wait --json
```

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

```bash theme={null}
youka deps ensure --for url
```

## 参考

<Columns cols={2}>
  <Card title="账户" icon="key" href="/zh/cli/account">
    登录、退出登录，并检查认证状态。
  </Card>

  <Card title="点数" icon="coins" href="/zh/cli/credits">
    查看当前余额和即将过期的点数套餐。
  </Card>

  <Card title="计费" icon="credit-card" href="/zh/cli/billing">
    显示定价并创建结账或门户 URL。
  </Card>

  <Card title="项目" icon="folder" href="/zh/cli/projects">
    创建、查看、等待并更新项目。
  </Card>

  <Card title="导出" icon="file-video" href="/zh/cli/exports">
    渲染云端或本地导出产物并下载。
  </Card>

  <Card title="预设" icon="palette" href="/zh/cli/presets">
    管理可复用的渲染配置。
  </Card>

  <Card title="媒体" icon="image" href="/zh/cli/media">
    上传并管理可复用媒体资源。
  </Card>

  <Card title="任务" icon="list-check" href="/zh/cli/tasks">
    需要时检查底层任务状态。
  </Card>

  <Card title="依赖" icon="box" href="/zh/cli/deps">
    检查并安装 URL 导入和本地渲染依赖。
  </Card>

  <Card title="全局选项" icon="gear" href="/zh/cli/global-options">
    每个命令都可用的标志。
  </Card>
</Columns>

## 默认即可供 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 信封结构：

```json theme={null}
{
  "ok": true,
  "data": {
    /* command result */
  }
}
```

失败时：

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Human-readable description",
    "details": {
      /* optional */
    }
  }
}
```

完整列表请参见 [全局选项](/zh/cli/global-options)。

## 云端 vs 本地导出

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

```bash theme={null}
youka deps ensure --for render
```

完整工作流请参见 [导出](/zh/cli/exports)。

## 下一步

* [账户](/zh/cli/account) - 保存你的 API key
* [项目](/zh/cli/projects) - 创建并处理项目
* [导出](/zh/cli/exports) - 渲染最终的卡拉 OK 视频
* [AI agents](/zh/agents) - 在自动化工作流中驱动 CLI