TTSMaker Text-to-Speech API Overview

The TTSMaker API is a service provided by TTSMaker for developers, designed to facilitate the integration of TTSMaker's TTS services into programs and products.

The API is currently divided into two categories:

  1. Free API: This API is available for non-commercial use only, such as educational learning, open-source projects, and academic research. To gain access, you need to apply and provide project details for whitelist review. The review process may take 2-3 weeks, and if approved, you will receive a token via email.
  2. Commercial API: This API is available for commercial use and supports a wide range of applications, as long as they are legal and the user holds 100% copyright ownership. TTSMaker does not assume any legal responsibility for the generated content. Pricing and plans for the commercial API are determined based on usage and frequency. Please contact us for more details.

API Token Account Acquisition and Pricing Rules

If you require an API token, please contact us through the "Contact Us" link in the upper right corner of our website and briefly describe your integration scenario, usage frequency, usage amount, and usage requirements. We will evaluate your situation comprehensively and provide you with an exclusive token that meets your needs.

We also offer a test token called

that can be used to test the API. This test token has a weekly character conversion limit of 100,000. The remaining usage limit is displayed as follows(Please note that we reserve the right to adjust the API token pricing and usage rules in the future. We will notify users in advance of any changes that may affect them. ):

API List and API Invocation Process

Here is a list of the primary APIs available for use:

  1. Get Voice List
  2. Create TTS Order
  3. Check Token Status

Developers can use the following steps to implement text-to-speech conversion and playback using the provided APIs:

  1. Call "Get Voice List" API to get the list of supported languages and voices. This API provides information about the maximum character limit for each voice and unique IDs associated with them.
  2. Use "Create TTS Order" API to create an order for text-to-speech conversion. Upon successful order creation, the API will return a temporary URL for the hosted audio file (instead of the audio file stream). The temporary URL will be valid for 2 hours.
  3. Use the temporary URL to download and store the audio file or play the audio file directly.
  4. Call "Check Token Status" API to retrieve information about the token's character usage, maximum character limit, and other details.

By following the above steps, developers can efficiently use the provided APIs to convert text to speech and play it back in their applications.

API Details

1. Get Voice List

Get a list of the available languages and voices.




API request frequency limit (Maximum QPS)


URL Params


    token: str // required, your developer token
    language: str = None // optional, support language: ["en","zh","es","ja","ko","de","fr","it","ru","pt","tr","ms","th","vi","id","he"]

    # get all voices
    # get all en voices

Response Example

  "error_code": "",
  "status": "success",
  "error_details": "Query the list of voices successfully.",
  "token": "ttsmaker_demo_token",
  "language": "en",
  "api_max_qps": "5/second",
  "support_language_list": [
  "voices_id_list": [
  "voices_count": 26,
  "voices_detailed_list": [
      "id": 147,
      "name": "🔥Peter-🇺🇸United States Male (Hot + Unlimited)",
      "language": "en",
      "sample_mp3_url": "",
      "limit_text": 6000
      "id": 148,
      "name": "🔥Alayna-🇺🇸United States FeMale (Hot + Unlimited)",
      "language": "en",
      "sample_mp3_url": "",
      "limit_text": 6000


Error Code:

  • TOKEN_ERROR: Token is invalid

  • LANGUAGE_NOT_FOUND: Language not found

2. Create TTS Order

Create a TTS order. The Create TTS Order API allows you to submit a TTS order and receive a temporary URL to access the generated speech file.

Please note that the API does not return the speech file itself, but instead provides a URL to a temporary file that will be deleted after 2 hours. You can use this URL to play or download the speech file as part of your business process.




API request frequency limit (Maximum QPS)


POST Params


    token: str // required, your developer token
    text: str  // required, text to be converted to speech
    voice_id: int // required, voice id
    audio_format: str = 'mp3' // optional, audio format, optional value: mp3/wav/ogg/aac/opus, default mp3
    audio_speed: float = 1.0 // optional, audio speed, range 0.5-2.0, 0.5: 50% speed, 1.0: 100% speed, 2.0: 200% speed, default 1.0
    audio_volume: float = 0 // optional, audio volume, range 0-10, 1: volume+10%, 8: volume+80%, 10: volume+100%, default 0
    text_paragraph_pause_time: int = 0  // optional, auto insert audio paragraph pause time, range 500-5000, unit: millisecond, maximum 50 pauses can be inserted. If more than 50 pauses, all pauses will be canceled automatically. default 0


    POST /v1/create-tts-order HTTP/1.1
    Content-Type: application/json; charset=utf-8
    Connection: close
    Content-Length: 180

    {"token":"ttsmaker_demo_token","text":"test API","voice_id":"778","audio_format":"wav","audio_speed":"1.0","audio_volume":"0","text_paragraph_pause_time":"0"}

Response Example

      "error_code": "0",
      "status": "success",
      "error_details": "Successful Speech Synthesis. ",
      "unix_timestamp": 1677980022,
      "audio_file_url": "",
      "audio_file_type": "mp3",
      "audio_file_expire_time": 1677987222, // 2 hours 
      "tts_elapsed_time": "1.91s",
      "tts_order_characters": 10,
      "token_status": {
        "current_cycle_max_characters": 100000,
        "current_cycle_characters_used": 190,
        "current_cycle_characters_available": 49810,
        "remaining_days_to_reset_quota": 4.44,
        "history_characters_used": 190

Sample Code

JavaScript example code
const axios = require('axios');

const params = {
  token: 'ttsmaker_demo_token',
  text: 'test API',
  voice_id: 778,
  audio_format: 'wav',
  audio_speed: 1.0,
  audio_volume: 0,
  text_paragraph_pause_time: 0
};'', params)
  .then(function (response) {
  .catch(function (error) {

Python example code
import requests
import json

url = ''
headers = {'Content-Type': 'application/json; charset=utf-8'}
params = {
    'token': 'ttsmaker_demo_token',
    'text': 'test API',
    'voice_id': 778,
    'audio_format': 'wav',
    'audio_speed': 1.0,
    'audio_volume': 0,
    'text_paragraph_pause_time': 0
response =, headers=headers, data=json.dumps(params))
PHP example code
    'text' => 'test API',
    'voice_id' => 778,
    'audio_format' => 'wav',
    'audio_speed' => 1.0,
    'audio_volume' => 0,
    'text_paragraph_pause_time' => 0

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json; charset=utf-8'));
$response = curl_exec($ch);

echo $response;

Java example code

public class TTSMakerAPI {

    private final String USER_AGENT = "Mozilla/5.0";

    public static void main(String[] args) throws Exception {

        TTSMakerAPI http = new TTSMakerAPI();

        // Set developer token, text, voice ID and audio format
        String developerToken = "ttsmaker_demo_token";
        String text = "test API";
        int voiceId = 778;
        String audioFormat = "wav";

        // Create TTS order
        String url = "";
        String params = "{\"token\":\"" + developerToken + "\",\"text\":\"" + text + "\",\"voice_id\":\"" + voiceId + "\",\"audio_format\":\"" + audioFormat + "\",\"audio_speed\":\"1.0\",\"audio_volume\":\"0\",\"text_paragraph_pause_time\":\"0\"}";

        String ttsFileUrl = http.sendPost(url, params);

    // HTTP POST request
    private String sendPost(String url, String params) throws Exception {

        URL obj = new URL(url);
        HttpURLConnection con = (HttpURLConnection) obj.openConnection();

        // Add request header
        con.setRequestProperty("User-Agent", USER_AGENT);
        con.setRequestProperty("Content-Type", "application/json; charset=utf-8");

        // Send post request
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());

        int responseCode = con.getResponseCode();
        System.out.println("\nSending 'POST' request to URL : " + url);
        System.out.println("Post parameters : " + params);
        System.out.println("Response Code : " + responseCode);

        BufferedReader in = new BufferedReader(
                new InputStreamReader(con.getInputStream()));
        String inputLine;
        StringBuffer response = new StringBuffer();

        while ((inputLine = in.readLine()) != null) {

        // Print result
        return response.toString();
Golang example code
package main

import (

func main() {
    url := ""

    payload := map[string]interface{}{
        "token":            "ttsmaker_demo_token",
        "text":                       "Hello, World!",
        "voice_id":                   "778",
        "audio_format":               "mp3",
        "audio_speed":                1.0,
        "audio_volume":               0,
        "text_paragraph_pause_time": 0,

    jsonPayload, err := json.Marshal(payload)
    if err != nil {

    req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    if err != nil {

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("User-Agent", "TTSMaker API Client")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {


Error codes

  • POST_FIELD_ERROR : There is an error in the request body field
  • TOKEN_ERROR : Ttoken invalid
  • VOICE_ID_ERROR : Voice ID invalid
  • TEXT_LENGTH_ERROR : Text length invalid
  • INSERT_PAUSE_ERROR : The insert pause special tag included in the text is incomplete, or the insert pause exceeds the range limit of 100ms-5000ms
  • TOTAL_TOKEN_CHARACTERS_EXCEED_LIMIT : The total number of characters in the text exceeds the limit

  • TTS_GENERATION_ERROR :TTS generation error.

  unable to convert text, possible reasons: 
  1. The language 🔤 of the text does not match the selected language 🌐 
  2. Text cannot be broken into paragraphs, please add punctuation 
  3. The text contains special characters
  4. Use too many pause inserts ((⏱️=xxxx)), please reduce it

3. Check Token Status

Check the developer token's character quota, used characters, quota reset date and other information.




API request frequency limit (Maximum QPS)


URL Params


    token: str // required


Response Example

      "error_code": "0",
      "status": "success",
      "msg": "Token status query succeeded.",
      "current_time": "2023-01-04 21:33:52",
      "token": "ttsmaker_demo_token",
      "token_status": {
        "order_characters": 0,
        "token_max_period_characters": 100000,
        "token_current_period_characters_used": 46,
        "token_current_period_characters_available": 49954,
        "token_next_reset_time": 4.94,
        "token_history_characters_used": 46

Error Code:

  • TOKEN_ERROR: Token is invalid


1. How should I handle errors?

If the API returns an error code, the error should be handled based on the error code.

2. How do I use the API?

  • Contact us to apply for a dedicated token, or you can use a test token for testing purposes.
  • Follow the instructions and sample codes in the API documentation.
  • If you encounter any problems, you can contact us for assistance.

3. Is Free Text to Speech API (TTSMaker API) ?

Yes, you can use it for free, but there are some restrictions on the number of characters and the number of requests per second.

Additionally, please note that while the API is currently free to use, access is by invitation only and we reserve the right to adjust the rules and limitations in the future.

4. What information is required to apply for the API?

To apply for an API token, users must use the "Contact Us" form and provide information about their intended use case, frequency of use, and expected usage volume. If users have special requirements, they can mention them as well. We will thoroughly evaluate each application and, if appropriate, add the user to our invitation whitelist and issue a dedicated token with specific usage characters.

We emphasize that our primary objective is to establish a reliable API service that meets the needs of our users, and we do not retain any data. We will not share any information with third parties.

5. Can the API be used for commercial purposes?

Yes, you can use the API for commercial purposes. As described in our copyright terms, you own 100% of the copyright to the generated audio files and can use them in any scenario. For more information,

please refer to the copyright terms page at copyright_and_commercial_license_terms.