TTSForFree — Tài liệu lập trình viên

Xác thực

Dùng API key trong header X-API-Key. Với tích hợp chỉ chạy trên trình duyệt, nên proxy qua server để bảo mật.

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

Danh sách Ngôn ngữ & Giọng

Lấy danh sách ngôn ngữ

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

// Response (rút gọn)
{
  "Id": 1,
  "TotalRows": 74,
  "Message": null,
  "Data": [
    {
      "Id": 1,
      "Code": "af",
      "Name": "Afrikaans",
      "Description": null
    }
  ]
}

Lấy danh sách giọng hỗ trợ

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
    }
  ]
}

Lấy thông tin cấu hình

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

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

Tạo job TTS

Gửi text + tham số giọng. API hoạt động bất đồng bộ và trả về jobId ngay.

POST https://ttsforfree.com/api/tts/createby
Content-Type: application/json
X-API-Key: YOUR_API_KEY

{
    "Texts": "hello everybody",
    "Voice": "v1:YPj2X6j04RZcJdGzo-CC0GBpkJ985PD5X_VWU_nJkNzppGtbnxJL-dU_hglv",
    "Pitch": 0,
    "ConnectionId": "",
    "CallbackUrl":"" //option
}

// 200 Success
{
    "Id" : 1,
    "Message" : "Success (cache hit)",
    "Data" : "abc.mp3",
    "Status": "PENDING" //SUCCESS, ERROR 
}

Lấy tệp âm thanh

Lấy tệp âm thanh nếu trạng thái trả về thành công

GET https://ttsforfree.com/api/tts/StreamFile?filename=abc.mp3

Polly để lấy trạng thái job

Gọi API này mỗi 5s để kiểm tra trạng thái job

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

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

Webhooks

Có thể truyền callbackUrl khi tạo job. Hệ thống sẽ POST payload kèm chữ ký khi job hoàn tất.

POST https://your.app/webhooks/tts
Content-Type: application/json
X-TTS-Signature: sha256=...  // HMAC của body với webhook secret của bạn

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

Hãy verify chữ ký phía server, rồi phản hồi 200 OK.

Giới hạn & hạn ngạch

• Mặc định: 2.000 ký tự/yêu cầu, 30 yêu cầu/ngày (free tier)
• Bảo vệ burst: token bucket, 60 yêu cầu / 5 phút mỗi IP
• Liên hệ để nâng hạn mức / mục đích thương mại

Mã lỗi

400 Bad Request    // thiếu text hoặc tham số không hợp lệ
401 Unauthorized    // thiếu/sai API key
403 Forbidden       // vượt hạn ngạch, hoặc hành động không được phép
404 Not Found       // không tìm thấy jobId
409 Conflict        // job trùng (vi phạm idempotency)
429 Too Many       // bị giới hạn tốc độ
500 Server Error    // lỗi tạm thời, hãy retry với backoff

Thực hành tốt

• Khử trùng lặp bằng hash = sha256(text|voice|rate|volumn|pitch) để tận dụng cache.
• Ưu tiên Webhooks; tránh polling dày đặc.
• Triển khai exponential backoff khi gặp 429/5xx.
• Chia đoạn văn bản rất dài thành scene/paragraph để tăng thông lượng.