Give your product
a natural voice.

Documentation

Introduction

The SPEECHMA API turns text into natural speech. It is a plain REST API: you send JSON over HTTPS and get MP3 audio back. It works with any language that can make a web request, from cURL and Python to Node.js, PHP, Go, Java and no-code tools.

There are three endpoints: /tts makes the audio, /voices lists every voice, and /usage shows how much of your monthly quota is left.

Authentication

Every request needs your API key. You find it in your dashboard. Send it in the X-API-Key header, or as a Bearer token if your tool prefers that.

X-API-Key: sm_your_api_key

Authorization: Bearer sm_your_api_key

Plans and limits

Limits reset with each monthly billing cycle. Every successful reply also tells you how many characters you have left (see /tts).

POST /tts

Turns text into speech. On success the reply body is the MP3 file itself, so you can save it straight to disk or stream it to a player.

Headers

Body (JSON)

Example request

curl -X POST https://speechma.com/api/v1/tts \
  -H "X-API-Key: sm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world!","voice":"voice-1"}' \
  --output speech.mp3

import requests

response = requests.post(
    "https://speechma.com/api/v1/tts",
    headers={
        "X-API-Key": "sm_your_api_key",
        "Content-Type": "application/json",
    },
    json={"text": "Hello world!", "voice": "voice-1"},
)

if response.status_code == 200:
    with open("speech.mp3", "wb") as f:
        f.write(response.content)
    print("Saved speech.mp3")
else:
    print("Error:", response.json()["error"])

import fs from "node:fs";

const response = await fetch("https://speechma.com/api/v1/tts", {
  method: "POST",
  headers: {
    "X-API-Key": "sm_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Hello world!", voice: "voice-1" }),
});

if (response.ok) {
  fs.writeFileSync("speech.mp3", Buffer.from(await response.arrayBuffer()));
  console.log("Saved speech.mp3");
} else {
  console.error("Error:", (await response.json()).error);
}

$ch = curl_init('https://speechma.com/api/v1/tts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(['text' => 'Hello world!', 'voice' => 'voice-1']),
    CURLOPT_HTTPHEADER     => ['X-API-Key: sm_your_api_key', 'Content-Type: application/json'],
]);
$audio = curl_exec($ch);
$code  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($code === 200) {
    file_put_contents('speech.mp3', $audio);
}

Reply

# The body is the MP3 file. These headers show your quota:
Content-Type:      audio/mpeg
X-Chars-Used:      250
X-Chars-Remaining: 999750
X-Plan:            starter

{
  "success": false,
  "error": "Quota exceeded",
  "code": 429
}

GET /voices

Lists every voice you can use, including 456 premium HD voices ("hd": true). Use the voice_id in your /tts requests. Each voice is listed under the language it speaks, so ?language=Czech also returns HD and multilingual voices that speak Czech. A voice with "multilingual": true speaks the listed language when your text is written in it. styles lists the values you can send as style.

Query parameter

Reply

{
  "success": true,
  "total": 1041,
  "hd_total": 456,
  "voices": [
    {
      "voice_id": "voice-1",
      "name": "Adri",
      "language": "Afrikaans",
      "locale": "af-ZA",
      "gender": "Female",
      "hd": false,
      "multilingual": false,
      "styles": []
    },
    {
      "voice_id": "voice-584",
      "name": "Adam HD",
      "language": "English",
      "locale": "en-US",
      "gender": "Male",
      "hd": true,
      "multilingual": false,
      "styles": []
    }
    // ...and 1,025 more
  ]
}

GET /usage

Shows your plan, the characters you have used this cycle, what is left and when the cycle ends. Calling it does not use any characters.

{
  "success": true,
  "account": {
    "plan": "pro",
    "billing_cycle_end": "2026-12-10"
  },
  "quota": {
    "chars_limit": 50000000,
    "chars_used": 120450,
    "chars_remaining": 49879550,
    "usage_percent": 0.24
  }
}

Error codes

Every error comes back as JSON with "success": false, a readable "error" message and the number in "code".

More examples

Slower, deeper voice with a pause

{
  "text": "Welcome to the show. [break 1s] Let us begin.",
  "voice": "voice-1",
  "pitch": -20,
  "rate": -30
}

Check your quota before a long job

import requests

headers = {"X-API-Key": "sm_your_api_key"}
text = "Hello from my app!"

usage = requests.get("https://speechma.com/api/v1/usage", headers=headers).json()
if len(text) <= usage["quota"]["chars_remaining"]:
    audio = requests.post("https://speechma.com/api/v1/tts", headers=headers,
                          json={"text": text, "voice": "voice-1"})
    open("output.mp3", "wb").write(audio.content)
else:
    print("Not enough characters left this month")