Quick Start

This guide takes you from an API key to a finished Algerian voice-over: generate speech, switch the model and the voice, choose a dialect, check the price first, and direct the delivery with tone directions. It's all one endpoint, POST /tts.

​Generate speech

Send your text to POST /tts with a model and a voice. You get back a link to an MP3 file:

import os

import requests

API = "https://api.voice213.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['VOICE213_API_KEY']}"}

response = requests.post(
    f"{API}/tts",
    headers=HEADERS,
    json={"text": "مرحبا بيكم في Voice213", "model": "voice213-lite", "voice": "nariman"},
    timeout=300,
)
response.raise_for_status()
result = response.json()

with open("hello.mp3", "wb") as f:
    f.write(requests.get(result["audioUrl"], timeout=60).content)

print(result["model"], result["billableChars"], result["cost"], result["remainingCredit"])

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

const API = "https://api.voice213.com/api/v1";
const HEADERS = {
  Authorization: `Bearer ${process.env.VOICE213_API_KEY}`,
  "Content-Type": "application/json",
};

const response = await fetch(`${API}/tts`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ text: "مرحبا بيكم في Voice213", model: "voice213-lite", voice: "nariman" }),
});
const result = await response.json();
if (!response.ok) throw new Error(result.message ?? result.error);

const audio = await fetch(result.audioUrl);
await writeFile("hello.mp3", Buffer.from(await audio.arrayBuffer()));
console.log(result.model, result.billableChars, result.cost, result.remainingCredit);

curl -X POST https://api.voice213.com/api/v1/tts \
  -H "Authorization: Bearer $VOICE213_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "مرحبا بيكم في Voice213", "model": "voice213-lite", "voice": "nariman"}' \
  -o response.json

curl -s -o hello.mp3 "$(jq -r .audioUrl response.json)"

A successful response looks like this:

{
  "success": true,
  "audioUrl": "https://pub-5d56f47943d84bbda9b38f1a6f9962e6.r2.dev/tts/66f1c0a4e1b2c3d4e5f60718/1727254800000-9f3c2a7b1d4e6f80.mp3",
  "model": "voice213-lite",
  "voice": "nariman",
  "cost": 0.9,
  "currency": "DZD",
  "chars": 22,
  "billableChars": 100,
  "remainingCredit": 4999.1,
  "words": 4,
  "quality": "standard",
  "dailyProCount": 0,
  "dailyProLimit": null
}

• audioUrl is the voice-over, an MP3 file. It's also saved to your History in the web app. In the rare case the file can't be stored, it's a data: URL carrying the MP3 itself instead.
• chars is the characters Voice213 counts in your text (free tone directions and invisible characters left out, runs of spaces counted once), and billableChars what you paid for: every request is billed at least 100 characters.
• cost is what the request cost in dinars (DZD), and remainingCredit your API credit after it.

​Switch the model

Five models speak the same voices. Change model and nothing else:

{
  "text": "مرحبا بيكم في Voice213",
  "model": "voice213-pro-2",
  "voice": "nariman"
}

Get the same list, with today's prices, from GET /models. Leave model out and Voice213 Lite speaks. See Voice Models to compare them.

​Switch the voice

Voice213 has 30 voices, and every one works with every model. List them with GET /tts/voices:

curl https://api.voice213.com/api/v1/tts/voices \
  -H "Authorization: Bearer $VOICE213_API_KEY"

{
  "success": true,
  "data": {
    "voices": [
      { "id": "sohila", "name": "سهيلة", "nameEn": "Sohila", "gender": "female", "description": "صوت امرأة لطيف", "descriptionEn": "Soft female voice", "dialects": ["algerian", "tunisian", "libyan"] },
      { "id": "nariman", "name": "نريمان", "nameEn": "Nariman", "gender": "female", "description": "صوت امرأة هادئ", "descriptionEn": "Calm female voice", "dialects": ["algerian", "tunisian", "libyan"] },
      { "id": "ryad", "name": "رياض", "nameEn": "Riyad", "gender": "male", "description": "صوت رجل مرح", "descriptionEn": "Cheerful male voice", "dialects": ["algerian", "tunisian", "libyan"] }
    ],
    "defaultVoice": "nariman"
  }
}

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

​Choose a dialect

Every voice speaks three dialects. Set dialect to algerian (the default), tunisian or libyan:

{
  "text": "شنية أحوالك؟ اليوم عندنا عرض خاص على الساعات.",
  "model": "voice213-lite-2",
  "voice": "amine",
  "dialect": "tunisian"
}

Write the script in the dialect you ask for: the voice follows your words and pronounces them with that dialect's accent. See Dialects.

​Check the price first

POST /tts/estimate takes the same text and model and returns the price without generating anything. It's free:

{
  "success": true,
  "model": "voice213-pro-2",
  "chars": 22,
  "billableChars": 100,
  "pricePer1MChars": 12000,
  "cost": 1.2,
  "currency": "DZD",
  "balance": 4999.1,
  "enough": true
}

See Estimate Cost.

​Get the audio in the response

If you'd rather have the audio inside the response than a link, name the voice with voiceId instead of voice: the response carries the WAV file as a data URL, and nothing is stored. It takes the same models and voices:

{
  "text": "مرحبا بيكم في Voice213",
  "model": "voice213-lite",
  "voiceId": "nariman",
  "dialect": 1
}

import base64

audio = response.json()["data"]["audio"]  # "data:audio/wav;base64,<audio>"
with open("hello.wav", "wb") as f:
    f.write(base64.b64decode(audio.split(",", 1)[1]))

See the inline format in the reference.

​Direct the delivery

A tone direction is a short instruction in parentheses, placed before the words it applies to. The voice performs it instead of reading it, and it isn't billed when it's at most 100 characters long, parentheses included:

{
  "text": "(نبرة حماسية ومنعشة) خويا، شفت الساعة الجديدة؟ مقاومة للماء وبسوار جلدي أصلي!",
  "model": "voice213-pro-2",
  "voice": "ryad"
}

This text has 56 characters without the direction; the request is billed the 100-character minimum. Get the full list of tones from GET /tts/tones. See Tone Directions.

​Troubleshooting

​Next steps