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

# Utiliser Youka depuis des assistants IA (MCP)

> Connectez Claude Code, Cursor, Codex ou n’importe quel client MCP à Youka et créez des vidéos karaoké et des lyric videos en discutant.

Youka dispose d’un serveur MCP. [MCP](https://modelcontextprotocol.io) (Model Context Protocol) est la méthode standard permettant aux assistants IA de se connecter à des outils externes. Une fois connecté, vous pouvez demander à votre assistant des choses comme « make a karaoke video of \~/Music/song.mp3 » et il crée le projet dans votre compte Youka, attend la fin du traitement, puis vous donne le lien de l’éditeur ou un lien de téléchargement.

Le serveur fonctionne avec n’importe quel client MCP qui prend en charge les serveurs distants (Streamable HTTP) avec un en-tête personnalisé, comme Claude Code, Cursor et Codex.

> [!NOTE]
>
> Les applications officielles Youka pour ChatGPT et Claude arrivent bientôt. En attendant, utilisez un
> client de cette page avec une clé API Youka.

## Ce dont vous avez besoin

* Un compte Youka avec des crédits. Le serveur MCP utilise les mêmes crédits que l’application web. Voir [Understanding credits](https://docs.youka.io/fr/web/understanding-credits.md).
* Une clé API Youka. Créez-en une sur [online.youka.io/account](https://online.youka.io/account) dans **API keys**. Voir [Authentication](https://docs.youka.io/fr/api/authentication.md).

Détails du serveur :

| Paramètre | Valeur |
| - | - |
| URL | `https://mcp.youka.io/mcp` |
| Transport | Streamable HTTP |
| Auth | `Authorization: Bearer YOUR_API_KEY` |

> [!WARNING]
>
> Votre clé API donne un accès complet à votre compte Youka et à ses crédits. Ne la mettez pas
> dans des fichiers ou dépôts partagés. Si une clé fuit, supprimez-la depuis la page de votre
> compte et créez-en une nouvelle.

## Connecter votre assistant

> [tab] Claude Code
>
> Exécutez ceci dans votre terminal en remplaçant `YOUR_API_KEY` par votre clé :
>
> ```bash theme={null}
> claude mcp add --transport http youka https://mcp.youka.io/mcp \
>   --header "Authorization: Bearer YOUR_API_KEY"
> ```
>
> Vérifiez que la connexion est bien établie :
>
> ```bash theme={null}
> claude mcp list
> ```
>
> Vous devriez voir `youka: https://mcp.youka.io/mcp (HTTP) - ✔ Connected`.
>
> Par défaut, le serveur n’est ajouté que pour le dossier courant. Ajoutez `--scope user` pour utiliser Youka dans tous les dossiers.

> [tab] Cursor
>
> Ouvrez `~/.cursor/mcp.json` (pour tous les projets) ou `.cursor/mcp.json` dans le dossier de votre projet, et ajoutez le serveur `youka` :
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "youka": {
>       "url": "https://mcp.youka.io/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:YOUKA_API_KEY}"
>       }
>     }
>   }
> }
> ```
>
> Définissez `YOUKA_API_KEY` dans l’environnement depuis lequel Cursor démarre, ou remplacez `${env:YOUKA_API_KEY}` par votre clé. Ensuite, ouvrez la section MCP des paramètres de Cursor et vérifiez que `youka` est activé.

> [tab] Codex
>
> Exécutez :
>
> ```bash theme={null}
> codex mcp add youka --url https://mcp.youka.io/mcp \
>   --bearer-token-env-var YOUKA_API_KEY
> ```
>
> Ou ajoutez ceci vous-même à `~/.codex/config.toml` :
>
> ```toml theme={null}
> [mcp_servers.youka]
> url = "https://mcp.youka.io/mcp"
> bearer_token_env_var = "YOUKA_API_KEY"
> ```
>
> Codex lit la clé depuis la variable d’environnement `YOUKA_API_KEY`, donc définissez-la avant de démarrer Codex :
>
> ```bash theme={null}
> export YOUKA_API_KEY="YOUR_API_KEY"
> ```
>
> Exécutez `codex mcp list` pour vérifier que `youka` est activé.

> [tab] Other clients
>
> Tout client MCP qui prend en charge les serveurs distants avec des en-têtes personnalisés fonctionne. Utilisez :
>
> * **URL:** `https://mcp.youka.io/mcp`
> * **Transport:** Streamable HTTP (parfois appelé « HTTP »)
> * **Header:** `Authorization: Bearer YOUR_API_KEY`
>
> Le serveur n’utilise pas de sessions, aucun autre réglage n’est donc nécessaire.

## Essayer

Parlez à votre assistant en langage naturel. Par exemple :

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

Une demande typique de karaoké se déroule comme suit :

**1. Upload**

L’assistant demande à Youka un lien d’upload et envoie votre fichier. L’upload
est gratuit.

**2. Check the cost**

Il vérifie combien de crédits le projet utilisera et compare avec votre
solde.

**3. Create the project**

Youka supprime les voix et synchronise les paroles. Cela prend quelques minutes. L’assistant
vérifie l’état jusqu’à ce que le projet soit prêt.

**4. Edit or export**

Vous recevez un lien pour ouvrir le projet dans l’éditeur Youka. Si vous demandez
le fichier vidéo, l’assistant l’exporte et vous donne un lien de téléchargement.

Créer un projet ne rend jamais une vidéo à lui seul. Vous décidez quand exporter, afin de pouvoir d’abord corriger les paroles ou le style, soit dans le chat soit dans l’[éditeur Youka](https://docs.youka.io/fr/web/using-studio.md).

## Ce que l’assistant peut faire

| Tool | What it does | Uses credits |
| - | - | - |
| `get_account` | Affiche votre compte, votre solde de crédits et vos limites d’upload. | No |
| `list_presets` | Liste vos [presets](https://docs.youka.io/fr/web/presets.md) de style enregistrés. | No |
| `prepare_upload` | Crée un lien d’upload pour un fichier audio ou vidéo sur votre ordinateur. | No |
| `quote_project` | Affiche le coût d’un nouveau projet. | No |
| `create_karaoke_video` | Crée un projet de karaoké modifiable (voix supprimées, paroles synchronisées) à partir d’un fichier. | Yes |
| `create_lyric_video` | Crée un projet de lyric video modifiable (audio d’origine, paroles synchronisées) à partir d’un fichier. | Yes |
| `list_projects` | Liste vos projets, du plus récent au plus ancien. | No |
| `get_project` | Affiche l’état d’un projet (processing, ready, ou failed), les paroles, les stems, les exports et le lien de l’éditeur. | No |
| `sync_lyrics` | Synchronise à nouveau des paroles corrigées, ou retranscrit à nouveau la chanson. | Yes |
| `get_task` | Affiche l’état d’une synchronisation des paroles. | No |
| `quote_export` | Affiche le coût d’un export. | No |
| `export_video` | Rend le projet tel qu’il est actuellement enregistré, y compris vos modifications dans l’éditeur. | Yes |
| `get_export` | Affiche l’état d’un export et, lorsqu’il est prêt, un lien de téléchargement. | No |

## Crédits et sécurité

* **Les mêmes crédits que l’application web.** Créer un projet, resynchroniser les paroles et exporter coûtent la même chose que sur [online.youka.io](https://online.youka.io).
* **Le coût est vérifié d’abord.** Si vous n’avez pas assez de crédits, Youka refuse la demande et le précise. Rien n’est facturé.
* **Pas de double facturation.** Si l’assistant réessaie une requête après un timeout, Youka reconnaît la relance et renvoie le résultat d’origine au lieu de facturer à nouveau.
* **Les crédits s’achètent sur Youka.** L’assistant ne peut pas acheter de crédits. Pour en ajouter, voir [Buy more credits](https://docs.youka.io/fr/web/buy-credits.md).
* **Les outils payants ne s’exécutent que lorsque vous le demandez.** L’assistant est configuré pour ne créer des projets, resynchroniser les paroles ou exporter que lorsque vous le demandez.

## Dépannage

> [accordion] 401 Unauthorized, or the server shows as failed
>
> La clé API est manquante ou invalide. Vérifiez que l’en-tête est exactement
> `Authorization: Bearer yk_...`, avec un seul espace après `Bearer` et sans espaces
> supplémentaires ni guillemets dans la clé. Si vous avez supprimé la clé depuis la page de votre compte, créez-en une nouvelle
> et mettez à jour votre client. Pour les configurations Codex et Cursor qui lisent
> `YOUKA_API_KEY`, assurez-vous que la variable est définie dans l’environnement depuis lequel l’application
> démarre.

> [accordion] Not enough credits
>
> Demandez à l’assistant votre solde, ou vérifiez-le sur
> [online.youka.io](https://online.youka.io). Ensuite [buy more
> credits](https://docs.youka.io/fr/web/buy-credits.md) et réessayez.

> [accordion] The project failed
>
> Demandez à l’assistant d’afficher le projet. Il inclut l’erreur. Assurez-vous que le
> fichier est un fichier audio ou vidéo pris en charge et qu’il respecte les limites d’upload indiquées
> par votre compte.

> [accordion] The lyrics are wrong
>
> Donnez à l’assistant les paroles correctes et demandez-lui de les synchroniser à nouveau, ou ouvrez
> le lien de l’éditeur et [modifiez les paroles](https://docs.youka.io/fr/web/edit-lyrics.md) vous-même. Ensuite,
> exportez à nouveau.

## Documentation associée

* [AI agents](https://docs.youka.io/fr/agents.md) — utiliser le Youka CLI et la skill depuis un agent
* [Authentication](https://docs.youka.io/fr/api/authentication.md) — créer et utiliser des clés API
* [Understanding credits](https://docs.youka.io/fr/web/understanding-credits.md)


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