开发者API文档

TTSMaker 文本转语音 API 概述

TTSMaker API 是由 TTSMaker 提供的面向开发者的服务，旨在方便将 TTSMaker 的 TTS 服务集成到程序和产品中（转换服务由人工智能模型生成，音频可用于任何合法用途（包括商用），生成的内容不代表TTSMaker马克配音的态度或观点，TTSMaker 对生成的内容不承担任何法律责任）。

目前，该 API 分为两个类别：

  1. 免费 API（计划暂停）：此 API 仅供非商业用途，如教育学习、开源项目和学术研究等使用。要获得访问权限，您需要申请并提供项目详细信息进行白名单审核。审核过程可能需要2-4周时间，如果获得批准，您将通过电子邮件收到一个Token。
  2. 商业 API：此 API 适用于商业用途，并支持各种应用程序，音频可用于任何合法用途（包括商用），商业 API 的定价和计划根据使用量和频率确定（存在单独部署计算服务成本，暂不接受低于2000万字符/月用量合作申请），请联系我们获取更多详细信息。

API测试Token账户

如果您需要 API Token，请通过我们网站右上角的“联系我们”链接与我们联系，并简要描述您的集成场景、使用频率、使用量和使用要求。我们将全面评估您的情况，并为您提供符合您需求的专属Token。

我们还提供一个名为 

ttsmaker_demo_token
的测试Token，可用于测试 API。 此测试Token每周字符转换限制为 100,000。剩余使用限制显示如下（请注意，我们保留在将来调整 API Token定价和使用规则的权利。我们将提前通知可能影响用户的任何变更。）：

API Token账户
ttsmaker_demo_token
剩余字符限制：0.002 %
每周Token支持的最大字符数
50000 个字符
本周Token已使用的字符数
49999 个字符
本周Token剩余可用字符数
1 个字符
Token转换配额重置剩余天数
3.57 天

API列表及API调用流程

以下是可用的主要 API 的列表：

  1. 获取语音列表
  2. 创建TTS订单
  3. 检查Token状态

开发者可以按照以下步骤，使用提供的API实现文本转语音的转换和播放：

  1. 调用“获取语音列表”接口获取支持的语言和语音列表。 此 API 提供有关每个语音的最大字符限制以及与其关联的唯一 ID 的信息。
  2. 使用“创建TTS订单”API创建文字转语音订单。 成功创建订单后，API 将返回托管音频文件（而不是音频文件流）的临时 URL。 临时 URL 的有效期为 2 小时。
  3. 使用临时URL 下载并存储音频文件或直接播放音频文件。
  4. 调用“检查令牌状态”接口检索有关令牌的字符使用情况、最大字符限制等详细信息。

通过执行上述步骤，开发人员可以有效地使用提供的 API 将文本转换为语音并在应用程序中播放。

API 详细信息

1. Get Voice List 获取播音员列表

获取可用语言和语音的列表。

URL

https://api.ttsmaker.cn/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.cn/v1/get-voice-list?token=your_token
    # get all en voices
    https://api.ttsmaker.cn/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,
    1504,
    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.cn/samples/147.mp3",
      "limit_text": 6000
    },
    {
      "id": 148,
      "name": "🔥Alayna-🇺🇸United States Female (Hot + Unlimited)",
      "language": "en",
      "sample_mp3_url": "https://s5.ttsmaker.cn/samples/148.mp3",
      "limit_text": 6000
    },
    ...

}

Error Code:

  • TOKEN_ERROR： Token is invalid

  • LANGUAGE_NOT_FOUND： Language not found

2. Create TTS Order 创建语音合成订单

创建 TTS 订单。 创建 TTS 订单 API 允许您提交 TTS 订单并接收临时 URL 以访问生成的语音 文件。

请注意，API 不会返回语音文件本身，而是提供临时文件的 URL，该临时文件 2小时后将被删除。 作为您业务的一部分，您可以使用此 URL 播放或下载语音文件 过程。

URL

https://api.ttsmaker.cn/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/mp3/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.cn
    Connection: close
    Content-Length: 180

    {"token":"ttsmaker_demo_token","text":"test API","voice_id":"1504","audio_format":"mp3","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://s5.tts-file.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: 1504,
  audio_format: 'mp3',
  audio_speed: 1.0,
  audio_volume: 0,
  text_paragraph_pause_time: 0
};

axios.post('https://api.ttsmaker.cn/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.cn/v1/create-tts-order'
headers = {'Content-Type': 'application/json; charset=utf-8'}
params = {
    'token': 'ttsmaker_demo_token',
    'text': 'test API',
    'voice_id': 1504,
    'audio_format': 'mp3',
    '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' => 1504,
    'audio_format' => 'mp3',
    '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 = 1504;
        String audioFormat = "mp3";

        // Create TTS order
        String url = "https://api.ttsmaker.cn/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.cn/v1/create-tts-order"

    payload := map[string]interface{}{
        "token":            "ttsmaker_demo_token",
        "text":                       "Hello, World!",
        "voice_id":                   "1504",
        "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 查看Token状态

查看开发者Token的配额字符、已使用字符、配额重置日期等信息

URL

https://api.ttsmaker.cn/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.cn/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. 如何处理错误？

如果API返回错误代码，应根据错误代码来处理错误。

2. 如何使用API？

联系我们申请一个专用的令牌，或者您可以使用一个测试令牌进行测试。 按照API文档中的说明和示例代码进行操作。 如果遇到任何问题，可以联系我们寻求帮助。

3. 文本转语音API（TTSMaker API）是免费的吗？

目前已经不限期暂停免费API计划，我们保留在将来调整规则和限制的权利。

4. 申请API需要提供哪些信息？

要申请API令牌，用户必须使用“联系我们”表单，并提供关于他们的预期用途、使用频率和预期使用量的信息。如果用户有特殊要求，也可以提及。我们将对每个申请进行全面评估，并在适当的情况下将用户添加到我们的邀请白名单中，并发放具有特定使用字符的专用令牌。

我们强调，我们的主要目标是建立一个满足用户需求的可靠API服务，并且我们不会保留任何数据。我们不会与第三方分享任何信息。

5. API可以用于商业用途吗？

是的，您可以将API用于商业用途。根据我们的版权条款，您完全拥有生成的音频文件的版权，并且可以在任何场景中使用它们。有关更多信息，请参阅版权条款页面。