Quick Start

This guide takes you from an API key to working Arabic audio: generate speech, choose a voice, a model and a dialect, then transcribe the audio back into text.

You'll need an API key and some API credit. If you don't have them yet, follow Get Your API Key first. The examples read the key from the MENAVOICE_API_KEY environment variable.

Generate speech

Send your text to POST /tts. The audio comes back in the JSON response as a base64 string:

import base64
import os

import requests

API = "https://api.menavoice.ai/api"
HEADERS = {"x-api-key": os.environ["MENAVOICE_API_KEY"]}

response = requests.post(
    f"{API}/tts",
    headers=HEADERS,
    json={"text": "مرحباً بكم في مينا فويس", "voiceId": "layla"},
    timeout=120,
)
response.raise_for_status()
result = response.json()

with open("hello.mp3", "wb") as f:
    f.write(base64.b64decode(result["audio"]))

print(result["voice"], result["characters"])

import { writeFile } from "node:fs/promises";

const API = "https://api.menavoice.ai/api";
const HEADERS = {
  "x-api-key": process.env.MENAVOICE_API_KEY,
  "Content-Type": "application/json",
};

const response = await fetch(`${API}/tts`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ text: "مرحباً بكم في مينا فويس", voiceId: "layla" }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);

await writeFile("hello.mp3", Buffer.from(result.audio, "base64"));
console.log(result.voice, result.characters);

curl -X POST https://api.menavoice.ai/api/tts \
  -H "x-api-key: $MENAVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "مرحباً بكم في مينا فويس", "voiceId": "layla"}' \
  -o response.json

jq -r .audio response.json | base64 --decode > hello.mp3

A successful response looks like this:

{
  "audio": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjYwLjE2LjEwMAAAAAAAAAAA...",
  "mimeType": "audio/mpeg",
  "voice": "layla",
  "characters": 23
}

audio is the speech, base64-encoded.
mimeType is the audio format: audio/mpeg, an MP3 file. Read it rather than assuming, and pick the file extension or Content-Type from it.
voice is the voice that spoke.
characters is what the request was billed for: the length of your text.

Choose a voice

MenaVoice has 30 studio voices. List them with GET /tts/voices, which doesn't need an API key:

curl https://api.menavoice.ai/api/tts/voices

{
  "voices": [
    {
      "id": "noura",
      "nameAr": "نورة",
      "nameEn": "Noura",
      "descAr": "صوت مشرق وحيوي",
      "descEn": "Bright and lively",
      "gender": "female"
    }
  ]
}

Pass a voice's id as voiceId. If you leave voiceId out, Layla speaks. To hear every voice before you choose, open Voices.

Choose a model and a dialect

quality selects the model and dialectId steers the delivery toward a regional dialect. Here MenaVoice 2 reads a line in Saudi dialect with the voice Fahad:

{
  "text": "هلا والله! وش رايك نبدأ المشروع من اليوم؟",
  "voiceId": "fahad",
  "quality": "v2",
  "dialectId": "saudi"
}

`quality`	Model
`flash` (default)	MenaVoice 1v: fast and consistent
`pro`	MenaVoice 1.5: richer, studio-style delivery
`v2`	MenaVoice 2: our most expressive model
`clone`	MenaVoice Clone: a voice from your voice library

Every model costs the same. See Choosing a Model and Dialects for the details.

Transcribe it back

Send the file you just made to POST /stt/transcribe as multipart form data:

with open("hello.mp3", "rb") as f:
    response = requests.post(
        f"{API}/stt/transcribe",
        headers=HEADERS,
        files={"audio": ("hello.mp3", f, "audio/mpeg")},
        data={"language": "ar"},
        timeout=300,
    )
response.raise_for_status()
print(response.json()["text"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("audio", new Blob([await readFile("hello.mp3")], { type: "audio/mpeg" }), "hello.mp3");
form.append("language", "ar");

const response = await fetch("https://api.menavoice.ai/api/stt/transcribe", {
  method: "POST",
  headers: { "x-api-key": process.env.MENAVOICE_API_KEY },
  body: form,
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
console.log(result.text);

curl -X POST https://api.menavoice.ai/api/stt/transcribe \
  -H "x-api-key: $MENAVOICE_API_KEY" \
  -F "audio=@hello.mp3" \
  -F "language=ar"

{
  "text": "مرحباً بكم في مينا فويس",
  "minutes": 0.1,
  "mimeType": "audio/mpeg"
}

Troubleshooting

401: Missing or invalid Authorization header

The request reached MenaVoice without an x-api-key header. Check that MENAVOICE_API_KEY is set in the shell or process that runs your code.

401: Invalid or revoked API key

The key is mistyped, incomplete or was revoked. Copy it again, or create a new key under API Keys.

402: Insufficient API balance

Your API credit can't cover the request. Top up under API Billing and try again.

429: Too many requests

You sent more than 30 requests in a minute, or more requests at once than your concurrency allows. Wait for the number of seconds in the Retry-After header (or for running requests to finish) and retry. See Rate Limits.

The browser blocks the request (CORS)

The API doesn't accept requests from other websites' browser code, because that would expose your key. Call MenaVoice from your server and send the audio on to your front end. See Going to Production.

Next steps

Multi-speaker Dialogue

Give every line of a conversation its own voice.

Voice Cloning

Speak with your own voice or one from the community.

Going to Production

Security, retries, limits and monitoring.

API Reference

Every endpoint, parameter and error.

​Generate speech

​Choose a voice

​Choose a model and a dialect

​Transcribe it back

​Troubleshooting

​Next steps