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

# Dùng Youka từ trợ lý AI (MCP)

> Kết nối Claude Code, Cursor, Codex hoặc bất kỳ client MCP nào với Youka và tạo video karaoke và video lời bài hát bằng cách trò chuyện.

Youka có một máy chủ MCP. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) là cách tiêu chuẩn để các trợ lý AI kết nối với công cụ bên ngoài. Khi bạn kết nối xong, bạn có thể yêu cầu trợ lý những việc như “tạo một video karaoke từ \~/Music/song.mp3” và nó sẽ tạo dự án trong tài khoản Youka của bạn, chờ hoàn tất, rồi cung cấp link trình chỉnh sửa hoặc link tải xuống.

Máy chủ hoạt động với bất kỳ client MCP nào hỗ trợ máy chủ remote (Streamable HTTP) với header tuỳ chỉnh, như Claude Code, Cursor và Codex.

> [!NOTE]
>
> Ứng dụng Youka chính thức cho ChatGPT và Claude sẽ sớm ra mắt. Trước mắt, hãy dùng một
> client trên trang này cùng với Youka API key.

## Những gì bạn cần

* Một tài khoản Youka có credits. Máy chủ MCP dùng chung credits với web app. Xem [Understanding credits](https://docs.youka.io/vi/web/understanding-credits.md).
* Một Youka API key. Tạo tại [online.youka.io/account](https://online.youka.io/account) trong mục **API keys**. Xem [Authentication](https://docs.youka.io/vi/api/authentication.md).

Thông tin máy chủ:

| Cài đặt | Giá trị |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> API key của bạn cho phép truy cập đầy đủ vào tài khoản Youka và credits của bạn. Hãy giữ nó
> خارج các tệp và kho mã dùng chung. Nếu key bị lộ, hãy xoá nó trên
> trang tài khoản và tạo key mới.

## Kết nối trợ lý của bạn

> [tab] Claude Code
>
> Chạy lệnh sau trong terminal, thay `YOUR_API_KEY` bằng key của bạn:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Kiểm tra xem đã kết nối chưa:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Bạn sẽ thấy `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> Mặc định, máy chủ chỉ được thêm cho thư mục hiện tại. Thêm `--scope user` để dùng Youka trong mọi thư mục.

> [tab] Cursor
>
> Mở `~/.cursor/mcp.json` (cho mọi dự án) hoặc `.cursor/mcp.json` trong thư mục dự án của bạn, rồi thêm máy chủ `youka`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Đặt `YOUKA_API_KEY` trong môi trường mà Cursor được khởi chạy từ đó, hoặc thay `${env:YOUKA_API_KEY}` bằng key của bạn. Sau đó mở phần MCP trong cài đặt của Cursor và kiểm tra rằng `youka` đã được bật.

> [tab] Codex
>
> Chạy:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Hoặc tự thêm vào `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex đọc key từ biến môi trường `YOUKA_API_KEY`, vì vậy hãy đặt biến này trước khi bạn khởi chạy Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Chạy `codex mcp list` để kiểm tra rằng `youka` đã được bật.

> [tab] Other clients
>
> Bất kỳ client MCP nào hỗ trợ máy chủ remote với custom headers đều dùng được. Dùng:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (đôi khi gọi là "HTTP")
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> Máy chủ không dùng sessions, nên không cần cấu hình nào khác.

## Thử ngay

Hãy hỏi trợ lý bằng ngôn ngữ tự nhiên. Ví dụ:

```text theme={null}
How many Youka credits do I have?
```

```text theme={null}
Make a karaoke video of ~/Music/song.mp3. Transcribe the lyrics automatically.
```

```text theme={null}
Make a lyric video of ./demo.wav using my "Neon" preset, then export it in 1080p and give me the download link.
```

```text theme={null}
In my latest Youka project, the second verse should be "..." instead of "...". Fix the lyrics and sync them again.
```

Một yêu cầu karaoke điển hình sẽ diễn ra như sau:

**1. Tải lên**

Trợ lý yêu cầu Youka cung cấp link tải lên và tải tệp của bạn lên. Việc tải lên
là miễn phí.

**2. Kiểm tra chi phí**

Nó kiểm tra dự án sẽ dùng bao nhiêu credits và so sánh với số dư
của bạn.

**3. Tạo dự án**

Youka loại bỏ giọng hát và canh đồng bộ lời. Việc này mất vài phút. Trợ lý
kiểm tra trạng thái cho đến khi dự án sẵn sàng.

**4. Chỉnh sửa hoặc xuất**

Bạn nhận được một link để mở dự án trong trình chỉnh sửa Youka. Nếu bạn yêu cầu
tệp video, trợ lý sẽ xuất và cung cấp cho bạn link tải xuống.

Việc tạo dự án không tự render video. Bạn quyết định khi nào xuất, để có thể sửa lời hoặc phong cách trước, είτε trong chat hoặc trong [Youka editor](https://docs.youka.io/vi/web/using-studio.md).

## Trợ lý có thể làm gì

| Tool | Nó làm gì | Dùng credits |
| - | - | - |
| `get_account` | Hiển thị tài khoản, số dư credits và giới hạn tải lên của bạn. | No |
| `list_presets` | Liệt kê các style [presets](https://docs.youka.io/vi/web/presets.md) đã lưu của bạn. | No |
| `prepare_upload` | Tạo link tải lên cho một tệp audio hoặc video trên máy tính của bạn. | No |
| `quote_project` | Hiển thị chi phí của một dự án mới. | No |
| `create_karaoke_video` | Tạo một dự án karaoke có thể chỉnh sửa (đã loại giọng, lời đồng bộ) từ một tệp. | Yes |
| `create_lyric_video` | Tạo một dự án lyric-video có thể chỉnh sửa (audio gốc, lời đồng bộ) từ một tệp. | Yes |
| `list_projects` | Liệt kê các dự án của bạn, mới nhất trước. | No |
| `get_project` | Hiển thị trạng thái dự án (đang xử lý, sẵn sàng hoặc thất bại), lời, stems, exports và link trình chỉnh sửa. | No |
| `sync_lyrics` | Đồng bộ lại lời đã sửa, hoặc chép lời lại bài hát. | Yes |
| `get_task` | Hiển thị trạng thái của một lần đồng bộ lời. | No |
| `quote_export` | Hiển thị chi phí của một lần export. | No |
| `export_video` | Render dự án theo trạng thái đã lưu hiện tại, bao gồm các chỉnh sửa của bạn trong trình chỉnh sửa. | Yes |
| `get_export` | Hiển thị trạng thái của một export và, khi sẵn sàng, cung cấp link tải xuống. | No |

## Credits và an toàn

* **Cùng credits như web app.** Tạo dự án, đồng bộ lại lời và export có chi phí giống như trên [online.youka.io](https://online.youka.io).
* **Chi phí được kiểm tra trước.** Nếu bạn không đủ credits, Youka sẽ từ chối yêu cầu và thông báo rõ. Không có khoản nào bị trừ.
* **Không bị tính phí hai lần.** Nếu trợ lý thử lại yêu cầu sau khi bị timeout, Youka nhận diện lần thử lại và trả về kết quả ban đầu thay vì tính phí lần nữa.
* **Credits được mua trên Youka.** Trợ lý không thể mua credits. Để nạp thêm, xem [Buy more credits](https://docs.youka.io/vi/web/buy-credits.md).
* **Các tác vụ mất phí chỉ chạy khi bạn yêu cầu.** Trợ lý chỉ được hướng dẫn tạo dự án, đồng bộ lời hoặc export khi bạn yêu cầu.

## Khắc phục sự cố

> [accordion] 401 Unauthorized, hoặc máy chủ hiển thị là failed
>
> API key bị thiếu hoặc không hợp lệ. Hãy kiểm tra header có đúng chính xác
> `Authorization: Bearer yk_...`, với đúng một dấu cách sau `Bearer` và không có dấu cách
> thừa hoặc dấu ngoặc kép trong key. Nếu bạn đã xoá key trên trang tài khoản, hãy tạo key mới
> và cập nhật client của bạn. Với thiết lập Codex và Cursor đọc
> `YOUKA_API_KEY`, hãy đảm bảo biến đã được đặt trong môi trường mà ứng dụng
> được khởi chạy từ đó.

> [accordion] Không đủ credits
>
> Hãy hỏi trợ lý về số dư, hoặc kiểm tra trên
> [online.youka.io](https://online.youka.io). Sau đó [buy more
> credits](https://docs.youka.io/vi/web/buy-credits.md) và thử lại.

> [accordion] Dự án bị thất bại
>
> Hãy yêu cầu trợ lý hiển thị dự án. Nó sẽ bao gồm lỗi. Hãy đảm bảo
> tệp là định dạng audio hoặc video được hỗ trợ và nằm trong giới hạn tải lên hiển thị bởi
> tài khoản của bạn.

> [accordion] Lời bài hát sai
>
> Hãy nói cho trợ lý lời đúng và yêu cầu đồng bộ lại, hoặc mở
> link trình chỉnh sửa và tự [edit the lyrics](https://docs.youka.io/vi/web/edit-lyrics.md). Sau đó
> export lại.

## Tài liệu liên quan

* [AI agents](https://docs.youka.io/vi/agents.md) — dùng Youka CLI và skill từ một agent
* [Authentication](https://docs.youka.io/vi/api/authentication.md) — tạo và dùng API keys
* [Understanding credits](https://docs.youka.io/vi/web/understanding-credits.md)


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