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

# Usa Youka dagli assistenti AI (MCP)

> Collega Claude Code, Cursor, Codex o qualsiasi client MCP a Youka e crea video karaoke e lyric chattando.

Youka ha un server MCP. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) è lo standard con cui gli assistenti AI si collegano a strumenti esterni. Una volta connesso, puoi chiedere al tuo assistente cose come "crea un video karaoke di \~/Music/song.mp3" e lui crea il progetto nel tuo account Youka, aspetta che finisca e ti fornisce il link all’editor o un link per il download.

Il server funziona con qualsiasi client MCP che supporti server remoti (Streamable HTTP) con un header personalizzato, come Claude Code, Cursor e Codex.

> [!NOTE]
>
> Le app ufficiali Youka per ChatGPT e Claude arriveranno presto. Nel frattempo, usa un
> client da questa pagina con una chiave API Youka.

## Cosa ti serve

* Un account Youka con crediti. Il server MCP usa gli stessi crediti della web app. Vedi [Understanding credits](https://docs.youka.io/it/web/understanding-credits.md).
* Una chiave API Youka. Creane una su [online.youka.io/account](https://online.youka.io/account) in **API keys**. Vedi [Authentication](https://docs.youka.io/it/api/authentication.md).

Dettagli del server:

| Impostazione | Valore |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Trasporto | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> La tua chiave API dà accesso completo al tuo account Youka e ai suoi crediti. Tienila
> fuori da file e repository condivisi. Se una chiave viene compromessa, eliminala nella pagina del tuo
> account e creane una nuova.

## Collega il tuo assistente

> [tab] Claude Code
>
> Esegui questo nel terminale, sostituendo `YOUR_API_KEY` con la tua chiave:
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Verifica che si sia connesso:
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Dovresti vedere `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> Per impostazione predefinita, il server viene aggiunto solo per la cartella corrente. Aggiungi `--scope user` per usare Youka in ogni cartella.

> [tab] Cursor
>
> Apri `~/.cursor/mcp.json` (per ogni progetto) oppure `.cursor/mcp.json` nella cartella del tuo progetto e aggiungi il server `youka`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Imposta `YOUKA_API_KEY` nell’ambiente da cui viene avviato Cursor, oppure sostituisci `${env:YOUKA_API_KEY}` con la tua chiave. Poi apri la sezione MCP nelle impostazioni di Cursor e verifica che `youka` sia abilitato.

> [tab] Codex
>
> Esegui:
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Oppure aggiungi tu stesso questo a `~/.codex/config.toml`:
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex legge la chiave dalla variabile d’ambiente `YOUKA_API_KEY`, quindi impostala prima di avviare Codex:
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Esegui `codex mcp list` per verificare che `youka` sia abilitato.

> [tab] Other clients
>
> Funziona qualsiasi client MCP che supporti server remoti con header personalizzati. Usa:
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (a volte chiamato "HTTP")
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> Il server non usa sessioni, quindi non servono altre impostazioni.

## Provalo

Chiedi al tuo assistente in linguaggio naturale. Per esempio:

```text theme={null}
Quanti crediti Youka ho?
```

```text theme={null}
Crea un video karaoke di ~/Music/song.mp3. Trascrivi automaticamente il testo.
```

```text theme={null}
Crea un lyric video di ./demo.wav usando il mio preset "Neon", poi esportalo in 1080p e dammi il link per il download.
```

```text theme={null}
Nel mio ultimo progetto Youka, la seconda strofa dovrebbe essere "..." invece di "...". Correggi il testo e risincronizzalo.
```

Una tipica richiesta karaoke segue questo flusso:

**1. Upload**

L’assistente chiede a Youka un link di caricamento e carica il tuo file. Il caricamento
è gratuito.

**2. Check the cost**

Controlla quanti crediti userà il progetto e li confronta con il tuo
saldo.

**3. Create the project**

Youka rimuove la voce e sincronizza il testo. Questo richiede alcuni minuti. L’
assistente controlla lo stato finché il progetto non è pronto.

**4. Edit or export**

Ottieni un link per aprire il progetto nell’editor Youka. Se chiedi il
file video, l’assistente lo esporta e ti fornisce un link per il download.

La creazione di un progetto non esegue mai il rendering di un video da sola. Decidi tu quando esportare, così puoi prima correggere il testo o lo stile, sia in chat sia nell’[editor Youka](https://docs.youka.io/it/web/using-studio.md).

## Cosa può fare l’assistente

| Strumento | Cosa fa | Usa crediti |
| - | - | - |
| `get_account` | Mostra il tuo account, il saldo crediti e i limiti di upload. | No |
| `list_presets` | Elenca i tuoi [presets](https://docs.youka.io/it/web/presets.md) di stile salvati. | No |
| `prepare_upload` | Crea un link di caricamento per un file audio o video sul tuo computer. | No |
| `quote_project` | Mostra quanto costerà un nuovo progetto. | No |
| `create_karaoke_video` | Crea un progetto karaoke modificabile (voci rimosse, testo sincronizzato) da un file. | Sì |
| `create_lyric_video` | Crea un progetto lyric-video modificabile (audio originale, testo sincronizzato) da un file. | Sì |
| `list_projects` | Elenca i tuoi progetti, dal più recente. | No |
| `get_project` | Mostra lo stato di un progetto (processing, ready o failed), testo, stem, export e link editor. | No |
| `sync_lyrics` | Sincronizza di nuovo un testo corretto, oppure ritrascrive il brano. | Sì |
| `get_task` | Mostra lo stato di una sincronizzazione del testo. | No |
| `quote_export` | Mostra quanto costerà un export. | No |
| `export_video` | Esegue il rendering del progetto così com’è salvato, includendo le tue modifiche nell’editor. | Sì |
| `get_export` | Mostra lo stato di un export e, quando è pronto, un link per il download. | No |

## Crediti e sicurezza

* **Stessi crediti della web app.** Creare un progetto, risincronizzare il testo ed esportare costa come su [online.youka.io](https://online.youka.io).
* **Il costo viene controllato prima.** Se non hai abbastanza crediti, Youka rifiuta la richiesta e lo segnala. Non viene addebitato nulla.
* **Nessun doppio addebito.** Se l’assistente ritenta una richiesta dopo un timeout, Youka riconosce il tentativo e restituisce il risultato originale invece di addebitare di nuovo.
* **I crediti si acquistano su Youka.** L’assistente non può acquistare crediti. Per aggiungerne altri, vedi [Buy more credits](https://docs.youka.io/it/web/buy-credits.md).
* **Gli strumenti a pagamento vengono eseguiti solo quando lo chiedi.** All’assistente viene indicato di creare progetti, sincronizzare il testo o esportare solo quando lo richiedi.

## Risoluzione dei problemi

> [accordion] 401 Unauthorized, or the server shows as failed
>
> La chiave API manca o non è valida. Verifica che l’header sia esattamente
> `Authorization: Bearer yk_...`, con uno spazio dopo `Bearer` e senza spazi
> extra o virgolette dentro la chiave. Se hai eliminato la chiave nella pagina del tuo account, creane una nuova
> e aggiorna il tuo client. Per le configurazioni Codex e Cursor che leggono
> `YOUKA_API_KEY`, assicurati che la variabile sia impostata nell’ambiente da cui l’app
> viene avviata.

> [accordion] Not enough credits
>
> Chiedi all’assistente il tuo saldo, oppure controllalo su
> [online.youka.io](https://online.youka.io). Poi [buy more
> credits](https://docs.youka.io/it/web/buy-credits.md) e riprova.

> [accordion] The project failed
>
> Chiedi all’assistente di mostrarti il progetto. Include l’errore. Assicurati che il
> file sia un file audio o video supportato entro i limiti di upload mostrati dal
> tuo account.

> [accordion] The lyrics are wrong
>
> Comunica all’assistente il testo corretto e chiedigli di sincronizzarlo di nuovo, oppure apri
> il link dell’editor e [modifica il testo](https://docs.youka.io/it/web/edit-lyrics.md) tu stesso. Poi
> esporta di nuovo.

## Documentazione correlata

* [AI agents](https://docs.youka.io/it/agents.md) — usa la Youka CLI e la skill da un agente
* [Authentication](https://docs.youka.io/it/api/authentication.md) — crea e usa chiavi API
* [Understanding credits](https://docs.youka.io/it/web/understanding-credits.md)


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