Getting started

This guide takes you from nothing to a first voice turn against the hosted API.

1. Get a key

The API is invite-based during early access. Request access; when you are invited you receive an API key and your service base URL (e.g. https://api.kerai.io).

Keep the key server-side or inject it at build time. Never commit it.

2. Check the service

A plain REST call confirms your key and reachability.

curl https://api.kerai.io/health
# { "status": "ok" }

List the speech, language, and voice options available to you:

curl https://api.kerai.io/api/providers/catalog

3. Open a voice session

Voice runs over a WebSocket at /ws/voice. Open it, send a session.init, then stream the user's speech as audio.chunk events.

const ws = new WebSocket("wss://api.kerai.io/ws/voice");
 
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session.init",
    payload: { language: "ml-IN", mode: "server_audio" },
  }));
};
 
ws.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  switch (evt.type) {
    case "transcript.final":
      console.log("heard:", evt.payload.text);
      break;
    case "assistant.audio":
      playAudio(evt.payload.base64); // your playback
      break;
    case "function.call":
      handleToolCall(evt.payload); // see step 4
      break;
  }
};
 
// stream microphone audio
ws.send(JSON.stringify({
  type: "audio.chunk",
  payload: { base64: chunkBase64, mime: "audio/webm" },
}));

Prefer text instead of audio? Set mode: "client_text" and send text turns — ker-ai returns text. See interaction modes.

4. Handle a tool call

When the model decides to act, ker-ai emits function.call. Run the matching function in your app and send the result back with the same id; ker-ai folds it into the reply.

async function handleToolCall({ id, name, arguments: args }) {
  let result;
  if (name === "add_to_cart") {
    result = await cart.add(args.productId, args.quantity ?? 1);
  }
  ws.send(JSON.stringify({
    type: "function.result",
    payload: { id, result },
  }));
}

Now a user can say "ഇത് കാർട്ടിൽ ഇടൂ", ker-ai calls add_to_cart, and speaks your result back.

Next steps

• Read the API reference for the full event list and session config.
• Understand interaction modes and tool calling.

A Flutter SDK that wraps all of the above is planned but not yet published. Until then, integrate against the API as shown here.