Text-to-Speech Engine

This API converts text into natural-sounding speech audio. Instead of streaming raw binary data, this API generates the audio, hosts it in the cloud, and returns a direct MP3 link. This makes it perfect for Bots, HTML5 players, mobile apps, and other applications.

Endpoint

POST /api/v1/tts

Request Parameters

The following parameters are accepted in the request body:

Field	Type	Required	Description
text	string	Yes	The text to convert (Max ~200 chars recommended).
lang	string	Optional	Language code (Default: en). Examples: fr, es, ja, id.

Request Examples

cURL

curl -X POST https://heavstal.com.ng/api/v1/tts \
-H "Content-Type: application/json" \
-H "x-api-key: <YOUR_API_KEY>" \
-d '{"text": "Bonjour le monde", "lang": "fr"}'

JavaScript (Fetch)

const response = await fetch('https://heavstal.com.ng/api/v1/tts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '<YOUR_API_KEY>'
  },
  body: JSON.stringify({
    text: 'Bonjour le monde',
    lang: 'fr'
  })
});

const res = await response.json();
console.log(res.data.url);

Heavstal SDK

import { tools } from '@heavstal/api';

// The SDK returns the raw audio buffer instead of a hosted link
const audioBuffer = await tools.tts("Hello World", "en");

const fs = require('fs');
fs.writeFileSync('speech.mp3', audioBuffer);

Python

import requests

url = "https://heavstal.com.ng/api/v1/tts"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "<YOUR_API_KEY>"
}
payload = {
    "text": "Bonjour le monde",
    "lang": "fr"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json()["data"]["url"])

Response Examples

Success Response

{
  "status": "success",
  "creator": "HEAVSTAL TECH",
  "data": {
    "text": "Bonjour le monde",
    "language": "fr",
    "url": "https://files.catbox.moe/abc1234.mp3",
    "mimetype": "audio/mpeg"
  }
}

Error Response

{
  "status": "error",
  "error": "Text exceeds maximum allowed length."
}