语音信息 API：文本转语音 (TTS)

通过几行简单的代码，即可将文本内容转为语音信息（TTS），并以电话形式发送给全球任何地区的电话号码。PaaSoo 目前支持 60 多种语言的语音转换，在多语种、多场景下为您提供灵活、可靠的呼叫服务。如需开通或获取更多高级功能，请联系技术支持或您的客户经理。

1. 语音信息API 概述

本语音信息API（Voice Messaging API）将文本内容转换为语音后，通过电话呼叫目标号码并播放信息。适用场景包括：

实时 OTP (One-Time Password) 电话播报。
公告或营销信息来覆盖多语言受众。
自动提醒，如账单缴费或预约提示，以电话形式增强通知到达率。

注意：某些国家或地区对语音呼叫存在严格限制，尤其是用于营销用途时；在开展此类业务前，请先确认符合当地法规。

2. 调用方式

调用方式

HTTP Method：GET
请求地址：https://api.paasoo.cn/voice/tts

请先确保拥有 key 和 secret，并在调用时通过查询参数（QueryString）进行传递。

3. 请求示例

GET https://api.paasoo.cn/voice/tts?key=API_KEY&secret=API_SECRET&from=85299998888&to=8618911111111&lang=en-GB&text=Your+code+1%2C2%2C3%2C4%2C5&repeat=2

示例说明：

text 参数中的 + 和 %2C 均为 URL 编码示例，当中逗号 , 用于适度停顿。
repeat=2 表示该消息内容会在一次通话中连续播报两遍。

4. 请求参数说明

参数	类型	必填	描述	示例
key	string	是	API Key（字母或数字构成，共 8 位），用于唯一标识您的账户。可在PaaSoo 客户端后台获取。	Abcdefgh
secret	string	是	API Secret（字母或数字构成，共 8 位），与 `key` 配合使用以进行身份验证。可在PaaSoo 客户端后台获取。	Abc123EF
from	string	是	主叫号码 (Caller ID)，仅支持 + 数字或数字形式（最大 20 位）。如需自定义请联系技术支持。	+85299998888
to	string	是	目标号码，包含国家区号。例如中国号码 18912345678 国家区号为 86，则写为 8618912345678。	8618912345678
lang	string	是	播报语言代码，详见支持语言列表或单独文档。若您需要更多语言，请联系技术支持。	zh-CN
text	string	是	发送内容，用 UTF-8 + URL 编码。可在语音文本中插入停顿、语速调节标签（详见下方的语音内容参数说明）。	Your+code+1%2C2%2C3%2C4%2C5
repeat	integer	否	重复播报次数，可设置 1～10，默认 1。	2
voice	string	否	可设定播报声线：woman（女声，默认）或 man（男声）。	woman
volume	string	否	语音的音量级别。绝对值：以从0.0 到 100.0（从最安静到最大声，例如75）的数字表示，默认值为100.0。或使用常量值： silent（0）-静音 x-soft（20）-非常小的音量 soft（40）-小音量 medium（60）-中等音量 loud（80）-大音量 x-loud（100，默认值）-非常大的音量	100/ loud
time_limit	integer	否	最大通话时长限制（秒），0 或不填表示不限制。	10
max_wait_time	integer	否	最大呼叫等待时间（秒）。超出则停止拨号并挂断。	30

5. 响应参数说明

参数	类型	描述	示例
messageid	string	单条语音信息的唯一标识。	015bd4-d6dfa7-58w
status	string	API 响应状态： 0 - success：成功 2 - Missing parameters：缺少必要参数 3 - Invalid parameters：参数格式错误 4 - Invalid credentials：`key` 或 `secret` 错误 5 - Unauthorized IP：IP 限制 6 - Invalid phone number：号码格式错误 7 - Invalid sender id：`from` 参数格式错误 8 - Message bombing detected：3秒内重复请求 9 - Quota exceeded：欠费或信用额度不足 10 - Throttling error：超过限速 11 - System error：系统错误	0 - success
status_code	string	与 status 对应的描述信息。	Missing parameters

5.1 成功示例

{
    "status": "0",
    "messageid": "015bd4-d6dfa7-58w"
}

5.2 失败示例

{
    "status": "2",
    "status_code": "Missing parameters."
}

6. 语音内容参数说明

为了使语音信息更自然且易于理解，您可通过停顿或语速调节实现灵活控制。以下标签可直接嵌入到 text 参数（需 URL 编码后）：

标签	属性	描述	示例
<break>	time	插入停顿。单位可为秒 (s) 或毫秒 (ms)。	1s/500ms
<prosody>	rate	设置语音播放速率，默认基准为 1，可在 0~3 之间调节。	0.1

使用示例：

用逗号 , 分隔：

Hello, your login token is 1,8,3,4,0.

逗号会产生短暂停顿。

用 <break> 标签分割：

hello, your token is <break time="1s"/>1<break time="500ms"/>8<break time="500ms"/>3<break time="500ms"/>4<break time="500ms"/>0.

精准控制停顿时长。

用 <prosody> 控制语速：

Your token is <prosody rate="0.1">1,8,3,4,0</prosody>.

语速放慢到原速率的 0.1 倍。

7. 代码示例

以下是在几种流行的编程语言中集成语音消息 (TTS) API 的简单代码示例。

Python
Node.js
PHP
Java
Go

import requests

# API 接口端点
url = "https://api.paasoo.cn/voice/tts"

# 查询参数
params = {
    "key": "API_KEY",                # 替换为您的 API Key
    "secret": "API_SECRET",          # 替换为您的 API Secret
    "from": "+85299998888",          # 主叫号码 (Caller ID)
    "to": "8618912345678",            # 目标号码
    "lang": "zh-CN",                 # 语言代码
    "text": "您的验证码是 1,2,3,4,5",   # 要转换为语音的文本
    "repeat": 2                      # 播放次数
}

try:
    # 发送 HTTP GET 请求
    response = requests.get(url, params=params)
    response.raise_for_status()
    
    # 解析并打印 JSON 响应
    data = response.json()
    if data.get("status") == "0":
        print("语音消息发送成功，messageid:", data.get("messageid"))
    else:
        print(f"语音消息发送失败，status: {data.get('status')}, message: {data.get('status_code')}")

except requests.exceptions.RequestException as e:
    print(f"请求失败: {e}")

const axios = require('axios'); // 运行: npm install axios

// API 接口端点
const url = 'https://api.paasoo.cn/voice/tts';

// 查询参数
const params = {
    key: 'API_KEY',               // 替换为您的 API Key
    secret: 'API_SECRET',         // 替换为您的 API Secret
    from: '+85299998888',         // 主叫号码 (Caller ID)
    to: '8618912345678',           // 目标号码
    lang: 'zh-CN',                // 语言代码
    text: '您的验证码是 1,2,3,4,5',  // 要转换为语音的文本
    repeat: 2                     // 播放次数
};

// 发送 HTTP GET 请求
axios.get(url, { params })
  .then((response) => {
      const data = response.data;
      if (data.status === '0') {
          console.log('语音消息发送成功，messageid:', data.messageid);
      } else {
          console.log('语音消息发送失败，status:', data.status, 'message:', data.status_code);
      }
  })
  .catch((error) => {
      console.error('请求失败:', error.message || error);
  });

<?php

// API 接口端点
$url = "https://api.paasoo.cn/voice/tts";

// 查询参数
$params = [
    "key" => "API_KEY",             // 替换为您的 API Key
    "secret" => "API_SECRET",       // 替换为您的 API Secret
    "from" => "+85299998888",       // 主叫号码 (Caller ID)
    "to" => "8618912345678",         // 目标号码
    "lang" => "zh-CN",              // 语言代码
    "text" => "您的验证码是 1,2,3,4,5",// 要转换为语音的文本
    "repeat" => 2                   // 播放次数
];

// 构建查询字符串并附加到 URL
$queryString = http_build_query($params);
$requestUrl = $url . '?' . $queryString;

// 初始化 cURL 会话
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// 执行请求
$response = curl_exec($ch);

if($e = curl_error($ch)) {
    echo "请求失败: " . $e;
} else {
    $data = json_decode($response, true);
    if ($data['status'] === "0") {
        echo "语音消息发送成功，messageid: " . $data['messageid'] . "\n";
    } else {
        echo "语音消息发送失败，status: " . $data['status'] . ", message: " . $data['status_code'] . "\n";
    }
}

// 关闭 cURL 会话
curl_close($ch);
?>

import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.HttpUrl;
import java.io.IOException;

// 确保在您的 pom.xml 或 build.gradle 中添加了 OkHttp 依赖
public class VoiceApiExample {
    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        // 构建带有查询参数的 URL
        HttpUrl.Builder urlBuilder = HttpUrl.parse("https://api.paasoo.cn/voice/tts").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");              // 替换为您的 API Key
        urlBuilder.addQueryParameter("secret", "API_SECRET");        // 替换为您的 API Secret
        urlBuilder.addQueryParameter("from", "+85299998888");        // 主叫号码 (Caller ID)
        urlBuilder.addQueryParameter("to", "8618912345678");          // 目标号码
        urlBuilder.addQueryParameter("lang", "zh-CN");               // 语言代码
        urlBuilder.addQueryParameter("text", "您的验证码是 1,2,3,4,5"); // 要转换的文本
        urlBuilder.addQueryParameter("repeat", "2");                 // 播放次数

        String url = urlBuilder.build().toString();

        // 构建请求
        Request request = new Request.Builder()
                .url(url)
                .get()
                .build();

        // 执行请求
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                System.out.println("响应: " + response.body().string());
            } else {
                System.out.println("请求失败，状态码: " + response.code());
            }
        } catch (IOException e) {
            System.err.println("请求失败: " + e.getMessage());
        }
    }
}

package main

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

func main() {
    // 解析基础 URL
    baseURL, err := url.Parse("https://api.paasoo.cn/voice/tts")
    if err != nil {
        fmt.Println("解析 URL 出错:", err)
        return
    }

    // 添加查询参数
    params := url.Values{}
    params.Add("key", "API_KEY")               // 替换为您的 API Key
    params.Add("secret", "API_SECRET")         // 替换为您的 API Secret
    params.Add("from", "+85299998888")         // 主叫号码 (Caller ID)
    params.Add("to", "8618912345678")           // 目标号码
    params.Add("lang", "zh-CN")                // 语言代码
    params.Add("text", "您的验证码是 1,2,3,4,5")  // 要转换的文本
    params.Add("repeat", strconv.Itoa(2))      // 播放次数

    // 编码参数并附加到 URL
    baseURL.RawQuery = params.Encode()

    // 发送 HTTP GET 请求
    resp, err := http.Get(baseURL.String())
    if err != nil {
        fmt.Println("请求失败:", err)
        return
    }
    defer resp.Body.Close()

json.Unmarshal(body, &result); err != nil {
        fmt.Println("解析 JSON 出错:", err)
        return
    }

    // 检查状态
    if status, ok := result["status"].(string); ok && status == "0" {
        fmt.Println("语音消息发送成功，messageid:", result["messageid"])
    } else {
        fmt.Printf("语音消息发送失败，status: %v, message: %v\n", result["status"], result["status_code"])
    }
}

8. 支持语言列表

PaaSoo 可为多达 60+ 种语言与方言提供 TTS 播报。见单独文档：《支持语言列表》，以获取更完整的语言类型、适用地区和示例。

9. 语音信息状态报告接收

在语音呼叫结束后，可通过回调URL（Webhook）接收语音状态报告，例如是否成功接通、播放时长等。请参见单独文档： “语音信息状态报告接收 ”。

同时，也可登录 PaaSoo 后台查看通话报告及详细记录。

10. 最佳实践与常见问题

参数安全：谨慎保管 key 和 secret，只应在后端服务器调用。
语言与方言：选择恰当的 lang 以提升用户理解度和接受度。
信息可理解度：在嘈杂环境中可能需要增加停顿时长或设定 repeat 播放次数。
时区与法律：注意当地法律场景，避免在敏感时间段或法律禁止时段呼叫。
费用与通时：语音服务成本通常比短信更高，请评估预算并在大量活跃拨打前与 PaaSoo 查询价格与额度。
故障排查：若呼叫失败，可根据返回的 status 与 status_code 检查是否为号码格式错误、余额不足、IP 未授权等。

11. 常见问题（FAQ）

主叫号码 (Caller ID) 允许使用任意号码吗？

需要先与 PaaSoo 或运营商确认可用的 Caller ID 列表。若需自定义 Caller ID，请联系客户经理进行报备或绑定。

语音信息可包含表情或非文本内容吗？

表情字符通常被忽略或转成描述字符，建议只发送纯文字（含标准标点符号）。

为什么接听后没有播报声音？

请检查 text 参数是否经过正确的 URL 编码，是否使用了超长停顿（或语速过慢），并确认服务器端无异常。

呼叫时长受哪些因素影响？

包括用户接听延迟、文本内容长度、repeat 次数，以及 time_limit 与 max_wait_time 是否设定等。

是否有并发或吞吐量限制？

并发能力取决于目的地国家运营商和客户业务需求。无论拨打量大小，均建议事先与 PaaSoo 沟通，以便准备合适的路由与带宽。

12. 附录

并发与吞吐量：由于不同目的地国家的政策和容量不同，请在任何呼叫量级（包含小规模及大规模并发时）事先与 PaaSoo 确认可行性，以预留足够的路由与带宽，应对突发流量。
回溯与审计：建议在业务系统中保存 messageid 与呼叫时间，方便日后审计和技术排查。
整合其他API：若需 SMS + 语音消息联动，可参考短信 API；目前转化追踪 API 仅适用于短信，不支持语音信息 API。

技术支持

如在 API 对接过程中遇到任何技术问题或业务疑问，欢迎随时联系我们的开发者支持团队：support@paasoo.com。我们将竭诚为您提供技术协助。

1. 语音信息API 概述​

2. 调用方式​

3. 请求示例​

4. 请求参数说明​

5. 响应参数说明​

5.1 成功示例​

5.2 失败示例​

6. 语音内容参数说明​

7. 代码示例​

8. 支持语言列表​

9. 语音信息状态报告接收​

10. 最佳实践与常见问题​

11. 常见问题（FAQ）​

12. 附录​