TTSForFree — Developer Documentation

REST API • Webhooks • SignalR realtime • Rate limits • Best practices

Overview

TTSForFree provides a low-latency, asynchronous Text‑to‑Speech pipeline. Your app creates a job via REST, we enqueue it (RabbitMQ), process with Python workers, and notify completion via SignalR or Webhooks. You can also poll a status endpoint if you prefer.

  • 70+ languages • 1,500+ voices (accents & styles)
  • Async job model: 200 Success → realtime updates → downloadable audio
  • Formats: mp3, wav(more coming)
  • Free tier for personal usage; commercial/API plans available

Authentication

Use an API key in the X-API-Key header. For browser-only integrations, prefer server-side proxying.

curl -X GET https://ttsforfree.com/api/health   -H "X-API-Key: YOUR_API_KEY"

List Languages & Voices

Retrieve supported languages

GET https://ttsforfree.com/api/common/getListLanguage

// Response (truncated)
{
  "Id": 1,
  "TotalRows": 74,
  "Message": null,
  "Data": [
    {
      "Id": 1,
      "Code": "af",
      "Name": "Afrikaans",
      "Description": null
    }
  ]
}

Retrieve supported voice

GET https://ttsforfree.com/api/common/getListVoice

// Response (truncated)
{
  "Id": 1,
  "TotalRows": 1820,
  "Message": null,
  "Data": [
    {
      "VoiceName": "v1:YPj2X6j04RZcJdGzo-CC0GBpkJ985PD5X_VWU_nJkNzppGtbnxJL-dU_hglv",
      "LanguageCode": "en",
      "LanguageName": "English",
      "FreindlyName": "Brian Online (Natural) - English (United States)",
      "Gender": "Male",
      "CountryName": "United States",
      "VoicePersonalities": "Approachable, Casual, Sincere",
      "ReviewAudio": "/20251018/120c601e-d775-4c14-9bbf-7c7750de8945/120c601e-d775-4c14-9bbf-7c7750de8945.mp3",
      "TotalRequests": 701,
      "PercentInLang": 0,
      "IsAllow": true,
      "MustUpgrade": false
    }
  ]
}

Retrieve configs

GET https://ttsforfree.com/api/common/GetConfigMaxLength

// Response (truncated)
{
  "Id": 1,
  "TotalRows": 0,
  "Message": null,
  "Data": 5000
}

Polly to get status job

Call this api every 5s to check job status

GET https://ttsforfree.com/api/tts/status/{jobId}

// 200 OK
{
    Id = 23,
    Status = "SUCCESS", //SUCCESS or ERROR
    FilePath = fileName, // abc123.mp3
    Message: ""
}

Webhooks

Optionally supply callbackUrl on job creation. We POST a signed payload when the job finishes.

POST https://your.app/webhooks/tts
Content-Type: application/json
X-TTS-Signature: sha256=...  // HMAC of body using your webhook secret

{
    Id = 23,
    Status = "SUCCESS", //SUCCESS or ERROR
    FilePath = fileName, // abc123.mp3
    Message: ""
}

Verify the signature server-side, then acknowledge with 200 OK.

Rate Limits & Quotas

  • Default: 2,000 characters/request, 30 requests/day (free tier)
  • Burst protection: token bucket, 60 req / 5 min per IP
  • Contact us for higher limits / commercial usage

Error Codes

400 Bad Request    // missing text or invalid params
401 Unauthorized    // missing/invalid API key
403 Forbidden       // over quota, or action not allowed
404 Not Found       // jobId not found
409 Conflict        // duplicate job (idempotency violation)
429 Too Many       // rate limited
500 Server Error    // transient issue, retry with backoff

Best Practices

  • Deduplicate by hash = sha256(text|voice|rate|volumn|pitch) to benefit from cache hits.
  • Use Webhooks; avoid tight polling loops.
  • Implement exponential backoff on 429/5xx.
  • Split very long text into scenes/paragraphs to improve throughput.

Licensing & Terms

Free tier is for personal/non-commercial usage. Commercial usage and API redistribution require a separate license. See Terms of Service and Privacy Policy for details, or contact thai00436@gmail.com.