> ## 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.

# 从 AI 助手使用 Youka（MCP）

> 将 Claude Code、Cursor、Codex 或任何 MCP 客户端连接到 Youka，通过聊天创建卡拉 OK 和歌词视频。

Youka 提供了一个 MCP 服务器。[MCP](https://modelcontextprotocol.io)（Model Context Protocol，模型上下文协议）是 AI 助手连接外部工具的标准方式。连接后，你可以让助手执行诸如“为 \~/Music/song.mp3 制作一个卡拉 OK 视频”之类的请求，它会在你的 Youka 账号中创建项目，等待处理完成，并给你编辑器链接或下载链接。

该服务器适用于任何支持带自定义请求头的远程（Streamable HTTP）服务器的 MCP 客户端，例如 Claude Code、Cursor 和 Codex。

> [!NOTE]
>
> 面向 ChatGPT 和 Claude 的官方 Youka 应用即将推出。在此之前，请使用本页中的客户端并配合 Youka API key。

## 你需要什么

* 一个有余额（credits）的 Youka 账号。MCP 服务器与网页版使用相同的 credits。参见 [Understanding credits](https://docs.youka.io/zh/web/understanding-credits.md)。
* 一个 Youka API key。在 [online.youka.io/account](https://online.youka.io/account) 的 **API keys** 下创建。参见 [Authentication](https://docs.youka.io/zh/api/authentication.md)。

服务器信息：

| Setting | Value |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> 你的 API key 可对你的 Youka 账号及其 credits 进行完全访问。不要把它放进共享文件和代码仓库中。如果 key 泄露，请在账号页面删除它并创建新的 key。

## 连接你的助手

> [tab] Claude Code
>
> 在终端中运行以下命令，将 `YOUR_API_KEY` 替换为你的 key：
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> 检查是否连接成功：
>
> ```bash theme={null}
> claude mcp list
> ```
>
> 你应该会看到 `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`。
>
> 默认情况下，服务器只会为当前文件夹添加。添加 `--scope user` 可在每个文件夹中使用 Youka。

> [tab] Cursor
>
> 打开 `~/.cursor/mcp.json`（用于所有项目）或你项目文件夹中的 `.cursor/mcp.json`，并添加 `youka` 服务器：
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> 在启动 Cursor 的环境中设置 `YOUKA_API_KEY`，或将 `${env:YOUKA_API_KEY}` 替换为你的 key。然后打开 Cursor 设置中的 MCP 部分，检查 `youka` 是否已启用。

> [tab] Codex
>
> 运行：
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> 或者手动把以下内容添加到 `~/.codex/config.toml`：
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex 会从 `YOUKA_API_KEY` 环境变量中读取 key，因此请在启动 Codex 前设置它：
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> 运行 `codex mcp list` 检查 `youka` 是否已启用。

> [tab] Other clients
>
> 任何支持带自定义请求头的远程服务器的 MCP 客户端都可以使用。使用：
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP（有时也叫 “HTTP”）
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> 该服务器不使用会话（sessions），因此不需要其他设置。

## 试试它

用自然语言向助手提问。例如：

```text theme={null}
我还有多少 Youka credits？
```

```text theme={null}
为 ~/Music/song.mp3 制作一个卡拉 OK 视频。自动转录歌词。
```

```text theme={null}
用我的 “Neon” preset 为 ./demo.wav 制作一个歌词视频，然后导出 1080p 并把下载链接给我。
```

```text theme={null}
在我最新的 Youka 项目中，第二段歌词应该是 “...” 而不是 “...”。修正歌词并重新同步。
```

一个典型的卡拉 OK 请求大致流程如下：

**1. 上传**

助手向 Youka 获取上传链接并上传你的文件。上传是免费的。

**2. 检查费用**

它会检查该项目会消耗多少 credits，并与你的余额进行对比。

**3. 创建项目**

Youka 会移除人声并同步歌词。这需要几分钟。助手会持续检查状态，直到项目就绪。

**4. 编辑或导出**

你会得到一个链接，用于在 Youka 编辑器中打开项目。如果你请求视频文件，助手会将其导出并提供下载链接。

创建项目本身不会自动渲染视频。你可以自行决定何时导出，因此你可以先修正歌词或样式，无论是在聊天中还是在 [Youka editor](https://docs.youka.io/zh/web/using-studio.md) 中。

## 助手可以做什么

| Tool | What it does | Uses credits |
| - | - | - |
| `get_account` | 显示你的账号信息、credit 余额和上传限制。 | No |
| `list_presets` | 列出你保存的样式 [presets](https://docs.youka.io/zh/web/presets.md)。 | No |
| `prepare_upload` | 为你电脑上的一个音频或视频文件创建上传链接。 | No |
| `quote_project` | 显示新项目的预计费用。 | No |
| `create_karaoke_video` | 从单个文件创建可编辑的卡拉 OK 项目（移除人声、同步歌词）。 | Yes |
| `create_lyric_video` | 从单个文件创建可编辑的歌词视频项目（原始音频、同步歌词）。 | Yes |
| `list_projects` | 列出你的项目，按最新优先。 | No |
| `get_project` | 显示项目状态（processing、ready 或 failed）、歌词、stems、exports 和编辑器链接。 | No |
| `sync_lyrics` | 重新同步修正后的歌词，或重新转录歌曲。 | Yes |
| `get_task` | 显示歌词同步任务的状态。 | No |
| `quote_export` | 显示一次导出的预计费用。 | No |
| `export_video` | 按当前保存的状态渲染项目，包括你在编辑器中的修改。 | Yes |
| `get_export` | 显示导出状态，并在就绪时提供下载链接。 | No |

## Credits 与安全

* **与网页版相同的 credits。** 创建项目、再次同步歌词、以及导出，其费用与在 [online.youka.io](https://online.youka.io) 上相同。
* **先检查费用。** 如果你的 credits 不足，Youka 会拒绝请求并说明原因，不会扣费。
* **不会重复扣费。** 如果助手在超时后重试请求，Youka 会识别这是重试，并返回原始结果，而不是再次扣费。
* **Credits 在 Youka 内购买。** 助手无法购买 credits。要增加 credits，请参见 [Buy more credits](https://docs.youka.io/zh/web/buy-credits.md)。
* **付费工具仅在你要求时运行。** 只有当你提出要求时，助手才会创建项目、同步歌词或导出。

## 故障排查

> [accordion] 401 Unauthorized, or the server shows as failed
>
> API key 缺失或无效。请检查请求头是否严格为
> `Authorization: Bearer yk_...`，确保 `Bearer` 后有一个空格，并且 key 内部没有多余空格或引号。如果你在账号页面删除了该 key，请创建一个新的并更新你的客户端。对于通过
> `YOUKA_API_KEY` 读取 key 的 Codex 和 Cursor 配置，请确保该变量已在应用启动时所使用的环境中设置。

> [accordion] Not enough credits
>
> 让助手告诉你余额，或在
> [online.youka.io](https://online.youka.io) 查看。然后 [buy more
> credits](https://docs.youka.io/zh/web/buy-credits.md) 并再次发起请求。

> [accordion] The project failed
>
> 让助手展示该项目，其中包含错误信息。请确保文件是受支持的音频或视频格式，并且未超过账号所显示的上传限制。

> [accordion] The lyrics are wrong
>
> 将正确歌词告诉助手并让它重新同步，或打开编辑器链接并自行 [edit the lyrics](https://docs.youka.io/zh/web/edit-lyrics.md)。然后再导出一次。

## 相关文档

* [AI agents](https://docs.youka.io/zh/agents.md) — 在 agent 中使用 Youka CLI 和 skill
* [Authentication](https://docs.youka.io/zh/api/authentication.md) — 创建并使用 API keys
* [Understanding credits](https://docs.youka.io/zh/web/understanding-credits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.