Developer example · HTTP + Python + TypeScript
Add Darija speech to your application
Generate WAV speech with ASAT, then choose between a direct audio assistant and a transcript-first workflow. Includes a real voice sample and the native-audio starter.
Resources
Start with the text. Listen to the result.
ASAT-v3.1 · male-1 · saved voice example
هاد الخدمة كتعاون الناس يفهمو المعلومة بسرعة وبصوت واضح.
4.96 seconds. The text above is the exact synthesis input.
This is the existing Omneity Labs ASAT model-page sample, reused without changing the audio. It is a text-to-speech result, not a captured full conversation. The commands below use the current public asat alias. A new request can produce a different result.
Add speech without changing how your app answers.
For developers adding spoken notifications, spoken answers or a voice interface, ASAT turns final text into audio. Your application can supply that text directly, or obtain it from an assistant. Speech synthesis does not listen to the user or decide which action to take.
- 01Reviewed text
- 02ASAT speech request
- 03WAV response
- 04Playback in your app
Send input, a voice and an output format to POST /v1/audio/speech. Save the audio bytes as a WAV file. Keep the API key on your server or in your terminal.
Generate speech from your own text.
You need a Sawalni account, an API key, enabled ASAT access and enough API credits. The example calls the hosted service. No local model is installed.
Create a key · Check access · Check credits.
1. Save a request file
Download speech-request.json. Open it in a text editor. Replace input with your own text. Keep the JSON valid.
{
"model": "asat",
"input": "هاد الخدمة كتعاون الناس يفهمو المعلومة بسرعة وبصوت واضح.",
"voice": "male-1",
"response_format": "wav",
"stream": false
}2. Send it and save the WAV
export SAWALNI_API_KEY="your-key"
curl --fail-with-body --show-error https://api.sawalni.com/v1/audio/speech -H "Authorization: Bearer $SAWALNI_API_KEY" -H "Content-Type: application/json" --data-binary @speech-request.json --output speech.wavRun this from the folder containing your request file. Check the command’s exit status before playing speech.wav. On an HTTP error, curl can write the error body to that path; it is not an audio result.
3. Or read a UTF-8 text file with Python
Download speech.py. Save your text as message.txt in the same folder. Use Python 3.10+; the client uses only the standard library.
export SAWALNI_API_KEY="your-key"
python3 speech.py --text-file message.txt --output speech.wavThe client checks the response type and WAV signature before saving the file. It does not retry requests automatically.
Choose what happens before speech synthesis.
| Your task | Route | What to inspect |
|---|---|---|
| Read text aloud | Text → ASAT → audio | Text, pronunciation, voice and pauses |
| Respond to spoken input | Audio recording → Sawalni input_audio → reply → optional ASAT | Intent, reply and any tool action |
| Keep a transcript before responding | Audio recording → Daktilo → transcript → your app → optional ASAT | Recognized words before downstream use |
| Create captions | Daktilo → review → Sawalign → SRT | Words, word timings and cue breaks |
Choose direct audio input when the assistant should respond to the audio recording. Choose a separate transcription step when your workflow needs the recognized text as an artifact. These routes have different outputs. This article makes no speed or accuracy comparison between them.
Run the native-audio voice starter.
The published starter supplies a turn-based backend in Python and TypeScript. Sawalni receives the WAV through input_audio. A bounded tool loop produces the reply. ASAT can then speak it. There is no required Daktilo step on this route.
Set up and prepare your audio recording
git clone https://github.com/omneity-labs/starter-voice.git
cd starter-voice
git checkout e7690c9671fa4976bc3466a65f60477bebcd6f41
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r python/requirements.txt
export SAWALNI_API_KEY="your-key"
# Replace the input path with your own audio recording.
ffmpeg -i /absolute/path/to/input.webm -ac 1 -ar 16000 -c:a pcm_s16le recording.wav
AUDIO="$(pwd)/recording.wav"FFmpeg must be installed. Use 0.1–90 seconds of mono 16 kHz PCM16 WAV. Renaming WebM to .wav does not convert the audio.
Return text, or save a spoken reply
python python/src/main.py "$AUDIO"
# Optional: make another request and save its spoken reply.
python python/src/main.py "$AUDIO" --speak reply.wavEach command above makes a separate assistant request. The second also uses ASAT access and credits. Omit --speak for text only. The starter’s example tools return UTC time and roll a die; they do not operate an order or customer system.
TypeScript with Node 24+
From the starter root, with the same absolute AUDIO path and exported key:
cd typescript
npm ci
npm start -- "$AUDIO" reply.wavLocal HTTP adapter
From the Python folder, run python src/server.py. It binds to 127.0.0.1:3000. In another terminal, send WAV bytes:
curl --fail-with-body http://127.0.0.1:3000/api/voice -H 'Content-Type: audio/wav' --data-binary @recording.wavThe response is JSON with a reply field. This adapter is for local development. Add application authentication, rate limits and persistence before exposing it to users.
Keep text, language and script choices explicit.
The saved example is Darija in Arabic script. ASAT’s model page includes other language and script examples. A voice ID chooses a voice; it does not translate your text. Review pronunciation for the specific language, variety and script in your application.
To translate text before speech, use the Tarjamli example. To preserve and review an audio recording’s words, use the transcription and captions example. Tifinagh, Arabic and Latin are scripts. Amazigh includes varieties such as Tachelhit. Do not assume every script or variety has the same synthesis quality.
Check the reply before an application acts.
- The public speech contract limits tiers 0–5 to 1,000 input characters per request. WAV is the portable output choice.
- The voice starter is turn-based. It is not a streaming microphone or telephony server. Its requests have a 120-second timeout.
- The tool loop validates its allowlist and arguments and stops after six model rounds. It does not execute model-generated code.
- Model text is not proof that a transaction occurred. Connect real application tools with their own validation before claiming an action succeeded.
- Check access, credits, input format and HTTP errors. No automatic retries are added by this article.
Source and related capabilities
The saved audio metadata retains the original model, text, voice and hash. The source is the existing ASAT model-page example. It is separate from the native-audio starter demonstration. No full conversation result is invented here.
The GitHub starter is MIT licensed. It includes tests and editable transport, tool and voice modules. Read speech synthesis docs, chat/audio docs, and Daktilo transcription docs for each component’s current contract.
Generate speech from your own text ↑