> ## 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 из ИИ-ассистентов (MCP)

> Подключите Claude Code, Cursor, Codex или любой MCP-клиент к Youka и создавайте караоке и lyric-видео в чате.

У Youka есть MCP-сервер. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) — это стандартный способ, с помощью которого ИИ-ассистенты подключаются к внешним инструментам. После подключения вы можете попросить ассистента, например: «сделай караоке-видео из \~/Music/song.mp3» — и он создаст проект в вашем аккаунте Youka, дождётся завершения обработки и выдаст ссылку на редактор или ссылку для скачивания.

Сервер работает с любым MCP-клиентом, который поддерживает удалённые (Streamable HTTP) серверы с пользовательским заголовком, например Claude Code, Cursor и Codex.

> [!NOTE]
>
> Официальные приложения Youka для ChatGPT и Claude появятся скоро. А пока используйте
> клиент с этой страницы вместе с API-ключом Youka.

## Что нужно

* Аккаунт Youka с кредитами. MCP-сервер использует те же кредиты, что и веб-приложение. См. [Понимание кредитов](https://docs.youka.io/ru/web/understanding-credits.md).
* API-ключ Youka. Создайте его на странице [online.youka.io/account](https://online.youka.io/account) в разделе **API keys**. См. [Аутентификация](https://docs.youka.io/ru/api/authentication.md).

Параметры сервера:

| Параметр | Значение |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> Ваш API-ключ даёт полный доступ к вашему аккаунту Youka и его кредитам. Не храните его
> в общих файлах и репозиториях. Если ключ утёк, удалите его на странице аккаунта и
> создайте новый.

## Подключите ассистента

> [tab] Claude Code
>
> Выполните в терминале, заменив `YOUR_API_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}"
>       }
>     }
>   }
> }
> ```
>
> Задайте `YOUKA_API_KEY` в окружении, из которого запускается Cursor, или замените `${env:YOUKA_API_KEY}` на ваш ключ. Затем откройте раздел MCP в настройках Cursor и проверьте, что `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`, поэтому задайте её до запуска 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`
>
> Сервер не использует сессии, поэтому другие настройки не нужны.

## Попробуйте

Пишите ассистенту простыми словами. Например:

```text theme={null}
Сколько кредитов Youka у меня осталось?
```

```text theme={null}
Сделай караоке-видео из ~/Music/song.mp3. Распознай текст автоматически.
```

```text theme={null}
Сделай lyric-видео из ./demo.wav, используя мой пресет "Neon", затем экспортируй в 1080p и дай ссылку для скачивания.
```

```text theme={null}
В моём последнем проекте Youka второй куплет должен быть "..." вместо "...". Исправь текст и синхронизируй его снова.
```

Типичный запрос на караоке выглядит так:

**1. Загрузка**

Ассистент запрашивает у Youka ссылку для загрузки и загружает ваш файл. Загрузка
бесплатна.

**2. Проверка стоимости**

Он проверяет, сколько кредитов потребуется на проект, и сравнивает это с вашим
балансом.

**3. Создание проекта**

Youka удаляет вокал и синхронизирует текст. Это занимает несколько минут. Ассистент
проверяет статус, пока проект не будет готов.

**4. Правка или экспорт**

Вы получаете ссылку, чтобы открыть проект в редакторе Youka. Если вы попросите
файл видео, ассистент экспортирует его и выдаст ссылку для скачивания.

Создание проекта само по себе никогда не рендерит видео. Вы сами решаете, когда экспортировать, поэтому сначала можно исправить текст или стиль — либо в чате, либо в [редакторе Youka](https://docs.youka.io/ru/web/using-studio.md).

## Что умеет ассистент

| Tool | Что делает | Uses credits |
| - | - | - |
| `get_account` | Показывает ваш аккаунт, баланс кредитов и лимиты загрузки. | No |
| `list_presets` | Выводит список сохранённых [пресетов](https://docs.youka.io/ru/web/presets.md) стиля. | No |
| `prepare_upload` | Создаёт ссылку для загрузки одного аудио- или видеофайла с вашего компьютера. | No |
| `quote_project` | Показывает, сколько будет стоить новый проект. | No |
| `create_karaoke_video` | Создаёт редактируемый караоке-проект (вокал удалён, текст синхронизирован) из одного файла. | Yes |
| `create_lyric_video` | Создаёт редактируемый 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 |

## Кредиты и безопасность

* **Те же кредиты, что и в веб-приложении.** Создание проекта, повторная синхронизация текста и экспорт стоят столько же, сколько на [online.youka.io](https://online.youka.io).
* **Сначала проверяется стоимость.** Если кредитов недостаточно, Youka отклоняет запрос и сообщает об этом. Ничего не списывается.
* **Без двойных списаний.** Если ассистент повторяет запрос после тайм-аута, Youka распознаёт повтор и возвращает исходный результат вместо повторного списания.
* **Кредиты покупаются в Youka.** Ассистент не может купить кредиты. Чтобы пополнить баланс, см. [Купить ещё кредиты](https://docs.youka.io/ru/web/buy-credits.md).
* **Платные инструменты запускаются только по вашему запросу.** Ассистенту сказано создавать проекты, синхронизировать текст или экспортировать только когда вы об этом попросите.

## Устранение неполадок

> [accordion] 401 Unauthorized, or the server shows as failed
>
> API-ключ отсутствует или недействителен. Проверьте, что заголовок указан строго как
> `Authorization: Bearer yk_...` — с одним пробелом после `Bearer` и без лишних
> пробелов или кавычек внутри ключа. Если вы удалили ключ на странице аккаунта, создайте
> новый и обновите настройки клиента. Для конфигураций Codex и Cursor, которые читают
> `YOUKA_API_KEY`, убедитесь, что переменная задана в окружении, из которого запускается
> приложение.

> [accordion] Not enough credits
>
> Попросите ассистента показать ваш баланс или проверьте его на
> [online.youka.io](https://online.youka.io). Затем [купите ещё
> кредиты](https://docs.youka.io/ru/web/buy-credits.md) и повторите запрос.

> [accordion] The project failed
>
> Попросите ассистента показать проект — там будет указана ошибка. Убедитесь, что
> файл — поддерживаемый аудио- или видеоформат и он укладывается в лимиты загрузки,
> показанные в вашем аккаунте.

> [accordion] The lyrics are wrong
>
> Сообщите ассистенту правильный текст и попросите синхронизировать его снова, либо откройте
> ссылку на редактор и [отредактируйте текст](https://docs.youka.io/ru/web/edit-lyrics.md) вручную. Затем
> экспортируйте ещё раз.

## Связанные материалы

* [AI agents](https://docs.youka.io/ru/agents.md) — используйте Youka CLI и skill из агента
* [Authentication](https://docs.youka.io/ru/api/authentication.md) — создание и использование API-ключей
* [Understanding credits](https://docs.youka.io/ru/web/understanding-credits.md)


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