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

# Use o Youka a partir de assistentes de IA (MCP)

> Conecte o Claude Code, Cursor, Codex ou qualquer cliente MCP ao Youka e crie vídeos de karaokê e de letras conversando no chat.

O Youka tem um servidor MCP. O [MCP](https://modelcontextprotocol.io) (Model Context Protocol) é a forma padrão de assistentes de IA se conectarem a ferramentas externas. Depois de conectar, você pode pedir ao seu assistente coisas como "faça um vídeo de karaokê de \~/Music/song.mp3" e ele cria o projeto na sua conta do Youka, espera terminar e fornece o link do editor ou um link de download.

O servidor funciona com qualquer cliente MCP que suporte servidores remotos (Streamable HTTP) com um cabeçalho personalizado, como Claude Code, Cursor e Codex.

> [!NOTE]
>
> Os apps oficiais do Youka para ChatGPT e Claude chegarão em breve. Até lá, use
> um cliente desta página com uma chave de API do Youka.

## O que você precisa

* Uma conta do Youka com créditos. O servidor MCP usa os mesmos créditos do app web. Veja [Understanding credits](https://docs.youka.io/pt/web/understanding-credits.md).
* Uma chave de API do Youka. Crie uma em [online.youka.io/account](https://online.youka.io/account) em **API keys**. Veja [Authentication](https://docs.youka.io/pt/api/authentication.md).

Detalhes do servidor:

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

> [!WARNING]
>
> Sua chave de API dá acesso total à sua conta do Youka e aos créditos dela. Não
> a coloque em arquivos e repositórios compartilhados. Se uma chave vazar, exclua
> ela na página da sua conta e crie uma nova.

## Conecte seu assistente

> [tab] Claude Code
>
> Execute isto no seu terminal, substituindo `YOUR_API_KEY` pela sua chave:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Verifique se conectou:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Você deve ver `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> Por padrão, o servidor é adicionado apenas para a pasta atual. Adicione `--scope user` para usar o Youka em todas as pastas.

> [tab] Cursor
>
> Abra `~/.cursor/mcp.json` (para todos os projetos) ou `.cursor/mcp.json` na pasta do seu projeto e adicione o servidor `youka`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Defina `YOUKA_API_KEY` no ambiente a partir do qual o Cursor é iniciado, ou substitua `${env:YOUKA_API_KEY}` pela sua chave. Depois, abra a seção MCP nas configurações do Cursor e verifique se `youka` está habilitado.

> [tab] Codex
>
> Execute:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Ou adicione isto você mesmo a `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> O Codex lê a chave da variável de ambiente `YOUKA_API_KEY`, então defina-a antes de iniciar o Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Execute `codex mcp list` para verificar se `youka` está habilitado.

> [tab] Other clients
>
> Qualquer cliente MCP que suporte servidores remotos com cabeçalhos personalizados funciona. Use:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (às vezes chamado de "HTTP")
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> O servidor não usa sessões, então nenhuma outra configuração é necessária.

## Experimente

Peça ao seu assistente em linguagem simples. Por exemplo:

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

Um pedido típico de karaokê funciona assim:

**1. Upload**

O assistente pede ao Youka um link de upload e envia seu arquivo. Fazer upload
é grátis.

**2. Check the cost**

Ele verifica quantos créditos o projeto vai usar e compara com o seu saldo.

**3. Create the project**

O Youka remove os vocais e sincroniza as letras. Isso leva alguns minutos. O
assistente verifica o status até o projeto ficar pronto.

**4. Edit or export**

Você recebe um link para abrir o projeto no editor do Youka. Se você pedir o
arquivo de vídeo, o assistente exporta e fornece um link de download.

Criar um projeto nunca renderiza um vídeo por si só. Você decide quando exportar, então pode corrigir a letra ou o estilo antes, seja no chat ou no [Youka editor](https://docs.youka.io/pt/web/using-studio.md).

## O que o assistente pode fazer

| Tool | What it does | Uses credits |
| - | - | - |
| `get_account` | Mostra sua conta, saldo de créditos e limites de upload. | No |
| `list_presets` | Lista seus [presets](https://docs.youka.io/pt/web/presets.md) de estilo salvos. | No |
| `prepare_upload` | Cria um link de upload para um arquivo de áudio ou vídeo no seu computador. | No |
| `quote_project` | Mostra quanto vai custar um novo projeto. | No |
| `create_karaoke_video` | Cria um projeto de karaokê editável (vocais removidos, letras sincronizadas) a partir de um arquivo. | Yes |
| `create_lyric_video` | Cria um projeto de lyric video editável (áudio original, letras sincronizadas) a partir de um arquivo. | Yes |
| `list_projects` | Lista seus projetos, do mais recente para o mais antigo. | No |
| `get_project` | Mostra o status de um projeto (processing, ready ou failed), letras, stems, exports e link do editor. | No |
| `sync_lyrics` | Sincroniza novamente letras corrigidas ou transcreve a música novamente. | Yes |
| `get_task` | Mostra o status de uma sincronização de letras. | No |
| `quote_export` | Mostra quanto vai custar uma exportação. | No |
| `export_video` | Renderiza o projeto conforme está salvo no momento, incluindo suas edições no editor. | Yes |
| `get_export` | Mostra o status de uma exportação e, quando estiver pronta, um link de download. | No |

## Créditos e segurança

* **Mesmos créditos do app web.** Criar um projeto, sincronizar letras novamente e exportar custam o mesmo que em [online.youka.io](https://online.youka.io).
* **O custo é verificado primeiro.** Se você não tiver créditos suficientes, o Youka recusa a solicitação e informa isso. Nada é cobrado.
* **Sem cobranças duplicadas.** Se o assistente repetir uma solicitação após um timeout, o Youka reconhece a repetição e retorna o resultado original em vez de cobrar novamente.
* **Os créditos são comprados no Youka.** O assistente não pode comprar créditos. Para adicionar mais, veja [Buy more credits](https://docs.youka.io/pt/web/buy-credits.md).
* **Ferramentas pagas só rodam quando você pede.** O assistente é instruído a criar projetos, sincronizar letras ou exportar somente quando você solicitar.

## Solução de problemas

> [accordion] 401 Unauthorized, or the server shows as failed
>
> A chave de API está ausente ou é inválida. Verifique se o cabeçalho é exatamente
> `Authorization: Bearer yk_...`, com um espaço após `Bearer` e sem espaços extras
> ou aspas dentro da chave. Se você excluiu a chave na página da sua conta, crie uma nova
> e atualize seu cliente. Para configurações do Codex e do Cursor que leem
> `YOUKA_API_KEY`, verifique se a variável está definida no ambiente a partir do qual o app
> é iniciado.

> [accordion] Not enough credits
>
> Peça ao assistente seu saldo ou verifique em
> [online.youka.io](https://online.youka.io). Depois [buy more
> credits](https://docs.youka.io/pt/web/buy-credits.md) e peça novamente.

> [accordion] The project failed
>
> Peça ao assistente para mostrar o projeto. Ele inclui o erro. Verifique se o
> arquivo é um áudio ou vídeo suportado dentro dos limites de upload mostrados pela
> sua conta.

> [accordion] The lyrics are wrong
>
> Diga ao assistente as letras corretas e peça para sincronizá-las novamente, ou abra
> o link do editor e [edit the lyrics](https://docs.youka.io/pt/web/edit-lyrics.md) você mesmo. Depois
> exporte novamente.

## Documentos relacionados

* [AI agents](https://docs.youka.io/pt/agents.md) — use o Youka CLI e a skill a partir de um agente
* [Authentication](https://docs.youka.io/pt/api/authentication.md) — crie e use chaves de API
* [Understanding credits](https://docs.youka.io/pt/web/understanding-credits.md)


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