> ## Documentation Index
> Fetch the complete documentation index at: https://developers.namuai-lab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent vocal

> Une conversation parlée en haoussa : envoyez ce qu’une personne a dit, recevez la réponse en texte et en parole.

> [!WARNING]
>
> L’agent vocal est un **aperçu de recherche**. Servez-vous-en pour explorer et pour nous dire ce dont vous avez besoin, pas pour quoi que ce soit dont des personnes dépendent. Ses réponses peuvent être fausses, et il peut changer sans le préavis que nous donnons pour les modèles en bêta.

7 min

Converser avec l’agent vocal

## Vue d’ensemble

`POST /v1/converse` traite un tour de conversation. Vous envoyez ce que la personne a dit ; l’API renvoie ce qu’elle a entendu, une réponse écrite en haoussa, et cette réponse dite par Nadia. Faites écouter l’audio, enregistrez ce que la personne dit ensuite, et envoyez-le à nouveau.

* **Modèle :** `voice-agent` (recherche)
* **Langue :** haoussa
* **Personnage :** `nadia`
* **Ce qui est compté :** l’audio que vous envoyez plus la réponse parlée

Les mots entendus sont envoyés à **Google Gemini via OpenRouter**, qui rédige la réponse ; Namu ne conserve aucune conversation, seulement des métadonnées sur chaque appel (durée, statut, temps de réponse).

## Activer la permission

Les nouvelles clés n’incluent pas la permission `converse`. Quand vous créez une clé dans la [console](https://www.namuai-lab.com/fr/account/keys), cochez **Agent vocal**. Une clé sans cette permission reçoit `403 insufficient_scope`.

## Un tour de parole

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.namuai-lab.com/v1/converse \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  -F file=@hello.ogg \
  -F session_id=demo-42
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import base64
import os
import requests

with open("hello.ogg", "rb") as audio:
    turn = requests.post(
        "https://api.namuai-lab.com/v1/converse",
        headers={"Authorization": f"Bearer {os.environ['NAMU_API_KEY']}"},
        files={"file": audio},
        data={"session_id": "demo-42"},
        timeout=300,
    ).json()

print("Heard:", turn["heard"])
print("Reply:", turn["reply"])
open("reply.wav", "wb").write(base64.b64decode(turn["audio"]))
```

```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const form = new FormData();
form.append("file", new Blob([await readFile("hello.ogg")]), "hello.ogg");
form.append("session_id", "demo-42");

const turn = await fetch("https://api.namuai-lab.com/v1/converse", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.NAMU_API_KEY}` },
  body: form,
}).then((r) => r.json());

await writeFile("reply.wav", Buffer.from(turn.audio, "base64"));
```

```json Réponse theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "voice-agent",
  "persona": "nadia",
  "session_id": "demo-42",
  "heard": "sannu yaya kike",
  "reply": "Lafiya lau, na gode. Me zan iya taimaka maka da shi?",
  "audio": "UklGRiQAAABXQVZFZm10IBAAAAABAAEAwF0AAIC7AAACABAAZGF0YQAAAAA...",
  "sample_rate": 24000,
  "audio_seconds": 5.8
}
```

## Requête

**file** `file` *required*

Ce que la personne a dit. Tout format accepté par la [transcription](https://developers.namuai-lab.com/fr/capabilities/speech-to-text.md#audio-pris-en-charge).

**persona** `string` (default: nadia)

Qui répond. `nadia` est le seul personnage.

**session\_id** `string`

Votre propre identifiant pour la conversation, jusqu’à 100 caractères. Il revient dans la réponse pour que vous puissiez associer les tours ; l’API ne le conserve jamais.

## Ce qu’il ne fait pas encore

* **Pas de mémoire d’un tour à l’autre.** Chaque requête est indépendante ; l’API ne garde pas la conversation.
* **Pas de diffusion en continu.** La réponse arrive quand elle est prête, en un seul fichier.
* **Haoussa uniquement.**

Si aucune parole n’est trouvée dans l’enregistrement, la réponse est `422 nothing_heard` : demandez à la personne de parler à nouveau.

## Voir aussi

> [card] [Parler à l’agent vocal](https://developers.namuai-lab.com/fr/tutorials/talk-to-the-voice-agent.md)
>
> Tutoriel

> [card] [Référence de l’API](https://developers.namuai-lab.com/fr/api-reference/voice-agent/converse.md)
>
> POST /v1/converse


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