Skip to content
alfe.aiDocs

Voice overview

Voice lets you talk to your agent and hear it answer out loud. Alfe transcribes what you say, hands the text to the agent, and speaks the reply back. The agent works with text as usual, so it keeps its memory and tools.

Voice is a core capability of chat, not a separate agent or an add-on.

Where you can use voice

Section titled “Where you can use voice”

You can reach an agent by voice in these ways:

  • In the chat window. Select the phone button on a conversation on web, desktop, or mobile. Your spoken turns land in that conversation.
  • On a phone call. Give the agent a phone number and call it. The agent can also place outgoing calls.
  • By dictation. Select the microphone in the message box to turn speech into text you can edit. This doesn’t start a call.

What a voice conversation feels like

Section titled “What a voice conversation feels like”

Calls are built to feel like a normal conversation:

  • Real time. The agent starts speaking as soon as a reply is ready, rather than waiting for the whole answer.
  • Interruptible. Start talking and the agent stops and listens.

Convert speech from your own code

Section titled “Convert speech from your own code”

Two endpoints convert between text and speech directly, for an agent or for your own code acting as one. Authenticate with the agent’s API key, the same way as the rest of the Agent API.

Both endpoints check your balance first and return 402 if there aren’t enough credits. Both accept an Idempotency-Key header, so a retry bills once.

Text to speech

Section titled “Text to speech”

POST /voice/tts turns text into audio.

Terminal
curl https://api.alfe.ai/voice/tts \
  -H "Authorization: Bearer $ALFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your build finished."}' \
  --output speech.pcm
  • Send a JSON body with text, from 1 to 5,000 characters. You can also pass a voiceId.
  • Receive raw audio. The X-Sample-Rate, X-Channels, and X-Bit-Depth response headers describe it. That’s 24 kHz, mono, 16-bit PCM today, with no file header, so wrap it in a container such as WAV to play it.

Speech to text

Section titled “Speech to text”

POST /voice/stt transcribes audio.

Terminal
curl https://api.alfe.ai/voice/stt \
  -H "Authorization: Bearer $ALFE_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "x-sample-rate: 16000" \
  --data-binary @speech.pcm
  • Send raw 16-bit mono PCM, up to 10 MB. Strip any WAV header first, or it’s transcribed as noise. Set x-sample-rate to a value from 8000 to 48000. The default is 24000.
  • Receive JSON with the transcribed text and a confidence score.
Response
{ "data": { "text": "Your build finished.", "confidence": 0.98 } }

Use the agent tools

Section titled “Use the agent tools”

Agents have the same abilities as tools, voice_tts and voice_stt, on OpenClaw and terminal runtimes. They read and write audio files in the agent’s workspace and handle the WAV conversion.

Next steps

Section titled “Next steps”