API DOCS V2.0

API Summary

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 follow these steps to integrate text-to-speech conversion and playback functionalities using the provided APIs:

0. Subscription and API Key Creation: Subscribe to either a PRO or Studio level subscription as Lite level does not support this feature. Create your private API key on the Developer API Center page. Each account is permitted to create one API key, which can be deleted and re-created if necessary. For debugging convenience, TTSMaker provides an Online API Interactive Documentation accessible via the 'Online Debugging' button at the top right corner of the page.

1. Get Voice List API: This API retrieves a list of supported languages and voices, providing details such as the maximum character limits per voice and their unique IDs. For debugging purposes, the TTS conversion page’s UI allows users to explore different languages, view Voice IDs, and listen to sample Mp3 files.

2. Create TTS Order API: Use this API to generate a text-to-speech conversion order. 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 24 hours. Each TTS task completion will also include data about your account's cycle quota. All voices are deducted in regular character mode and do not support unlimited mode; more information can be found in the FAQ.

3. Use of Temporary URL: The temporary URL can be used to download the audio file or to play it directly within the 24-hour validity period.

4. Check Token Status API: This API allows for the retrieval of detailed information regarding the token's character usage and other account-specific details.

Note: The QPS (Queries Per Second) limit for each API key is set to 1 request per second. Exceeding this limit will result in an HTTP CODE 429 error.

By adhering to these guidelines, developers can effectively utilize the provided APIs for converting text to speech and integrating the playback in their applications.

API Details

1. Get Voice List

Get a list of the available languages and voices.

URL

https://api.ttsmaker.com/v2/get-voice-list?api_key=replace_this_demo_key

Click here to debug online

Method

GET/POST

API request frequency limit (Maximum QPS)

1/second

URL Params

param:

    api_key:  str // required, your api_key
    language: str = None // optional, support language: ["en", "zh", "es", "pt", "de", "fr", "it", "tr", "ru", "ja", "ko", "ms", "th", "vi", "id", "he", "fi", "sv", "nb", "da", "hi", "ar", "ro", "hu", "pl", "nl", "cs", "uk", "hr", "el", "sk", "bg", "sl", "ca", "ga", "lt", "mt", "et", "is", "lv", "ur", "ta", "mr", "te", "gu", "ml", "kn", "bn", "fa", "fi", "sw"]


example:

    # get all voices
    https://api.ttsmaker.com/v2/get-voice-list?api_key=your_api_key
    # get all en voices
    https://api.ttsmaker.com/v2/get-voice-list?api_key=your_api_key&language=en

bash curl code:

   curl -X 'GET' \
  'https://api.ttsmaker.com/v2/get-voice-list?api_key=replace_this_demo_key' \
  -H 'accept: application/json'


   curl -X 'GET' \
  'https://api.ttsmaker.com/v2/get-voice-list?language=en&api_key=replace_this_demo_key' \
  -H 'accept: application/json'

Response Example

{
  "error_code": 0,
  "error_summary": "",
  "msg": "Query the list of voices successfully. ",
  "user_email": "[email protected]",
  "language": "en",
  "support_language_list": [
    "en",
    "zh",
    "es",
    "ja",
     ...
  ],
  "voices_id_list": [
    147,
    148,
    663,
    666,
    777,
    778,
    779,
    780,
    2001,
    2002,
    2003,
    ...
  ],
  "voices_count": 26,
  "voices_detailed_list": [
    {
      "id": 147,
      "name": "🔥Peter-🇺🇸United States Male (Hot + Unlimited)",
      "language": "en",
      "audio_sample_file_url": "https://s2.ttsmaker-file.com/samples/pro_147.mp3",
      "text_characters_limit": 20000
    },
    {
      "id": 148,
      "name": "🔥Alayna-🇺🇸United States FeMale (Hot + Unlimited)",
      "language": "en",
      "audio_sample_file_url": "https://s2.ttsmaker-file.com/samples/pro_148.mp3",
      "text_characters_limit": 20000
    },
   {
      "id": 1480,
      "name": "Alayna-🇺🇸United States FeMale (V2 Multi-Emotion Version)",
      "language": "en",
      "audio_sample_file_url": "https://s2.ttsmaker-file.com/samples/pro_1480.mp3",
      "text_characters_limit": 20000,
      "is_support_emotion": true,
      "support_emotion_key_list": [  # This voice supports emotions. You can select an emotion key from the list. With this parameter in the TTS order API, you can return the TTS task data with emotion selection. For details, please see the subsequent description.
        "assistant",
        "chat",
        "customerservice",
        "newscast",
        "angry",
        "cheerful",
        "sad",
        "excited",
        "friendly",
        "terrified",
        "shouting",
        "unfriendly",
        "whispering",
        "hopeful"
      ]
    },
    ...

}

Error Code:

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/v2/create-tts-order

Click here to debug online

Method

POST

Request Format

Our API only accepts requests with the following Content-Type:

• Content-Type: application/json

Please ensure that all POST requests include a JSON body.

API request frequency limit (Maximum QPS)

1/second

POST Params

{
  "api_key": "replace_this_demo_key",
  "text": "Please fill in the text that needs to be converted to speech.",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1,
  "audio_volume": 0,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 0,
  "emotion_style_key": "",
  "emotion_intensity": 1
}

Example 1: Generate an mp3 audio file at 1.5x speed

{
  "api_key": "replace_this_demo_key",
  "text": "Here is an example that generates an mp3 audio file.",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1.5,
  "audio_volume": 0.8,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 0,
  "emotion_style_key": "",
  "emotion_intensity": 1
}

CURL CODE:

curl -X 'POST' \
  'https://api.ttsmaker.com/v2/create-tts-order' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "replace_this_demo_key",
  "text": "Here is an example that generates an mp3 audio file.",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1.5,
  "audio_volume": 0.8,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 0,
  "emotion_style_key": "",
  "emotion_intensity": 1
}'

Example 1: Response body

{
  "error_code": 0,
  "error_summary": "",
  "msg": "TTS Task Executed Successfully",
  "user_email": "[email protected]",
  "tts_task_characters_count": 52,
  "audio_download_url": "https://s5-8.ttsmaker-vip-file.com/file/2024-08-13-224440_166679.mp3",
  "audio_download_backup_url": "https://ttsmaker-file2.com/s5/file/2024-08-13-224440_166679.mp3",
  "audio_file_format": "mp3",
  "current_timestamp": 1723560281,
  "audio_file_expiration_timestamp": 1723646681,
  "is_demo_key": true,
  "account_status": {
    "quota_characters": 1000000,
    "characters_used": 40937,
    "available_quota": 959063,
    "subscription_period": "month",
    "subscription_next_reset_timestamp": 1725372332
  }
}

Example 2: Generate a word audio with a 3s pause before each word and a 10s pause at the end

Knowledge 1: How to use the [[break=1000]] tag

1. You can freely insert pauses in the text by using the [[break=1000]] tag. For example, [[break=1000]] means inserting a 1-second pause at this position.
2. [[break=0]] is for special purposes. You can use [[break=0]] between paragraphs to eliminate the default silence time between two paragraphs.
3. The longest time is 10 seconds. The parameter range of break is [[break=1]] -->[[break=10000]]. Multiple tags can be used continuously.

Knowledge 2: How to use the textparagraphpause_time parameter

The principle of the text_paragraph_pause_time parameter is to automatically replace line breaks with [[break=X]], for example, textparagraphpause_time=5000 means that all line breaks in the text are automatically replaced with [[break=5000]], and [[break=5000]]] means inserting a 5-second pause at this position.

0 means not to enable this parameter -1 means to replace and insert [[break=-0]] 1-10000 means to control the millisecond size of the automatically inserted pause tag.

{
  "api_key": "replace_this_demo_key",
  "text": "Shelf\nLibrarian\nThe stacks\nReturn\nFine\nMagazine\nCopier\nOverdue\nReading room\nReference room\n [[break=10000]]",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1.0,
  "audio_volume": 1.5,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 3000,
  "emotion_style_key": "",
  "emotion_intensity": 1

}
BASH CURL CODE:

curl -X 'POST' \
  'https://api.ttsmaker.com/v2/create-tts-order' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "replace_this_demo_key",
  "text": "Shelf\nLibrarian\nThe stacks\nReturn\nFine\nMagazine\nCopier\nOverdue\nReading room\nReference room\n [[break=10000]]",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1.0,
  "audio_volume": 1.5,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 3000,
  "emotion_style_key": "",
  "emotion_intensity": 1
}'

Example 2: Response body

{
  "error_code": 0,
  "error_summary": "",
  "msg": "TTS Task Executed Successfully",
  "user_email": "[email protected]",
  "tts_task_characters_count": 91,
  "audio_download_url": "https://s5-9.ttsmaker-vip-file.com/file/2024-08-13-230733_197903.mp3",
  "audio_download_backup_url": "https://ttsmaker-file2.com/s5/file/2024-08-13-230733_197903.mp3",
  "audio_file_format": "mp3",
  "current_timestamp": 1723561654,
  "audio_file_expiration_timestamp": 1723648054,
  "is_demo_key": true,
  "account_status": {
    "quota_characters": 1000000,
    "characters_used": 41392,
    "available_quota": 958608,
    "subscription_period": "month",
    "subscription_next_reset_timestamp": 1725372332
  }
}

Example 3: Generate an audio file that supports multiple emotions

You can view emoiton sounds with the E logo on the pro.ttsmaker.com/studio page. Or use the getvoicelist API to view all voices. If the voice id is supported, the voice data contains issupportemotion and the corresponding supportemotionkey_list

For example, the multi-emotion voice with voice_id 1480 supports ["assistant", "chat", "customerservice", "newscast", "angry", ...]. You can fill in angry as an emoiton key.

{
  "api_key": "replace_this_demo_key",
  "text": "I am very angry now because you lost the book.",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1,
  "audio_volume": 0,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 0,
  "emotion_style_key": "angry",
  "emotion_intensity": 2
}

BASH CURL CODE:

curl -X 'POST' \
  'https://api.ttsmaker.com/v2/create-tts-order' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "replace_this_demo_key",
  "text": "I am very angry now because you lost the book.",
  "voice_id": 1480,
  "audio_format": "mp3",
  "audio_speed": 1,
  "audio_volume": 0,
  "audio_pitch": 1,
  "audio_high_quality": 0,
  "text_paragraph_pause_time": 0,
  "emotion_style_key": "angry",
  "emotion_intensity": 2
}'

Example 3: Response body

{
  "error_code": 0,
  "error_summary": "",
  "msg": "TTS Task Executed Successfully",
  "user_email": "[email protected]",
  "tts_task_characters_count": 46,
  "audio_download_url": "https://s2v1.ttsmaker-vip-file.com/file/2024-08-13-231356_113746.mp3",
  "audio_download_backup_url": "https://ttsmaker-file2.com/s2v1/file/2024-08-13-231356_113746.mp3",
  "audio_file_format": "mp3",
  "current_timestamp": 1723562036,
  "audio_file_expiration_timestamp": 1723648436,
  "is_demo_key": true,
  "account_status": {
    "quota_characters": 1000000,
    "characters_used": 41438,
    "available_quota": 958562,
    "subscription_period": "month",
    "subscription_next_reset_timestamp": 1725372332
  }
}

Error Code:

3. Check Token Status

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

URL

https://api.ttsmaker.com/v2/get-token-status?api_key=replace_this_demo_key

Click here to debug online

Method

GET/POST

API request frequency limit (Maximum QPS)

1/second

URL Params

param:

    api_key:  str // required

example:

    https://api.ttsmaker.com/v2/get-token-status?api_key=replace_this_demo_key

bash curl code:

   curl -X 'GET' \
  'https://api.ttsmaker.com/v2/get-token-status?api_key=replace_this_demo_key' \
  -H 'accept: application/json'

Response Example

{
  "error_code": 0,
  "error_summary": "",
  "msg": "API_Key/Account status checked",
  "user_email": "[email protected]",
  "current_timestamp": 1723562903,
  "is_demo_key": true,
  "account_status": {
    "quota_characters": 1000000,
    "characters_used": 41438,
    "available_quota": 958562,
    "subscription_period": "month",
    "subscription_next_reset_timestamp": 1725372332
  }
}

Error Code: