Developer API

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.

URL

https://api.ttsmaker.com/v1/get-voice-list

Method

GET/POST

API request frequency limit (Maximum QPS)

5/second

URL Params

param:

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

example:
    # get all voices
    https://api.ttsmaker.com/v1/get-voice-list?token=your_token
    # get all en voices
    https://api.ttsmaker.com/v1/get-voice-list?token=your_token&language=en

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": [
    "en",
    "zh",
    "es",
    "ja",
    "ko",
    "de",
    "fr",
    "it",
    "ru",
    "pt",
    "tr",
    "ms",
    "th",
    "vi",
    "id",
    "he"
  ],
  "voices_id_list": [
    147,
    148,
    663,
    666,
    777,
    778,
    779,
    780,
    2001,
    2002,
    2003,
    2004,
    2503,
    2504,
    2505,
    2506,
    2507,
    2508,
    2509,
    2510,
    2511,
    2512,
    2596,
    2597,
    2598,
    2599
  ],
  "voices_count": 26,
  "voices_detailed_list": [
    {
      "id": 147,
      "name": "🔥Peter-🇺🇸United States Male (Hot + Unlimited)",
      "language": "en",
      "sample_mp3_url": "https://s5.ttsmaker.com/samples/147.mp3",
      "limit_text": 6000
    },
    {
      "id": 148,
      "name": "🔥Alayna-🇺🇸United States FeMale (Hot + Unlimited)",
      "language": "en",
      "sample_mp3_url": "https://s5.ttsmaker.com/samples/148.mp3",
      "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.

URL

https://api.ttsmaker.com/v1/create-tts-order

Method

POST

API request frequency limit (Maximum QPS)

1/second

POST Params

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

example:

    POST /v1/create-tts-order HTTP/1.1
    Content-Type: application/json; charset=utf-8
    Host: api.ttsmaker.com
    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": "https://s4.ttsmaker.com/file/2023-03-05-093341_165106.mp3",
      "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
};

axios.post('https://api.ttsmaker.com/v1/create-tts-order', params)
  .then(function (response) {
    console.log(response.data);
  })
  .catch(function (error) {
    console.log(error);
  });

Python example code

import requests
import json

url = 'https://api.ttsmaker.com/v1/create-tts-order'
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 = requests.post(url, headers=headers, data=json.dumps(params))
print(response.json())

PHP example code

 'ttsmaker_demo_token',
    '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);
curl_close($ch);

echo $response;

?>

Java example code

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;

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 = "https://api.ttsmaker.com/v1/create-tts-order";
        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);
        System.out.println(ttsFileUrl);
    }

    // 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.setRequestMethod("POST");
        con.setRequestProperty("User-Agent", USER_AGENT);
        con.setRequestProperty("Content-Type", "application/json; charset=utf-8");

        // Send post request
        con.setDoOutput(true);
        DataOutputStream wr = new DataOutputStream(con.getOutputStream());
        wr.writeBytes(params);
        wr.flush();
        wr.close();

        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) {
            response.append(inputLine);
        }
        in.close();

        // Print result
        System.out.println(response.toString());
        return response.toString();
    }
}

Golang example code

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://api.ttsmaker.com/v1/create-tts-order"

    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 {
        panic(err)
    }

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

    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 {
        panic(err)
    }
    defer resp.Body.Close()

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

    fmt.Println(string(body))
}

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.

URL

https://api.ttsmaker.com/v1/get-token-status

Method

GET/POST

API request frequency limit (Maximum QPS)

5/second

URL Params

param:

    token: str // required

example:

    https://api.ttsmaker.com/v1/get-token-status?token=your_token

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

FAQ

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.