Voice agent - Namu API

The voice agent is a research preview. Use it to explore and to tell us what you need, not for anything people depend on. Its answers can be wrong, and it may change without the notice we give for beta models.

Overview

POST /v1/converse runs one turn of a conversation. You send what the person said; the API returns what it heard, a reply written in Hausa, and the reply spoken by Nadia. Play the audio, record the next thing the person says, and send it again.

Model: voice-agent (research)
Language: Hausa
Persona: nadia
Counts: the audio you send plus the spoken reply

The words heard are sent to Google Gemini through OpenRouter, which writes the reply; Namu keeps no conversation, only metadata about each call (duration, status, timing).

Turn on the scope

New keys do not include the converse scope. When you create a key in the console, tick Voice agent. A key without it gets 403 insufficient_scope.

One turn

curl https://api.namuai-lab.com/v1/converse \
  -H "Authorization: Bearer $NAMU_API_KEY" \
  -F file=@hello.ogg \
  -F session_id=demo-42

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"]))

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"));

Response

{
  "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
}

Request

file

required

What the person said. Any format speech to text accepts.

string

default:"nadia"

Who answers. nadia is the only persona.

string

Your own id for the conversation, up to 100 characters. It comes back in the answer so you can match turns; the API never stores it.

What it does not do yet

No memory between turns. Each request stands alone; the API does not keep the conversation.
No streaming. The reply arrives once it is ready, as a whole file.
Hausa only.

If no speech is found in the recording, the answer is 422 nothing_heard: ask the person to speak again.

Talk to the voice agent

Tutorial

API reference

POST /v1/converse

​Overview

​Turn on the scope

​One turn

​Request

​What it does not do yet

​Related

Talk to the voice agent

API reference

Overview

Turn on the scope

One turn

Request

What it does not do yet

Related