語音訊息 API：文字轉語音 (TTS)

透過幾行簡單的程式碼，即可將文字內容轉為語音訊息（TTS），並以電話形式發送給全球任何地區的電話號碼。PaaSoo 目前支援 60 多種語言的語音轉換，在多語種、多場景下為您提供靈活、可靠的通話服務。如需開通或取得更多進階功能，請聯絡技術支援或您的客戶經理。

1. 語音訊息 API 概述

本語音訊息 API（Voice Messaging API）將文字內容轉換為語音後，透過電話呼叫目標號碼並播放訊息。適用場景包括：

即時 OTP (One-Time Password) 電話播報。
公告或行銷訊息來覆蓋多語言受眾。
自動提醒，如帳單繳費或預約提示，以電話形式增強通知到達率。

注意：某些國家或地區對語音通話存在嚴格限制，尤其是用於行銷用途時；在開展此類業務前，請先確認符合當地法規。

2. 呼叫方式

呼叫方式

HTTP Method：GET
請求地址：https://api.paasoo.com.tw/voice/tts

請先確保擁有 key 和 secret，並在呼叫時透過查詢參數（QueryString）進行傳遞。

3. 請求範例

GET https://api.paasoo.com.tw/voice/tts?key=API_KEY&secret=API_SECRET&from=85299998888&to=886912345678&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	是	目標號碼，包含國際電話代碼。例如台灣號碼 0912345678 國際電話代碼為 886，則寫為 886912345678。	886912345678
lang	string	是	播報語言代碼，詳見支援語言列表或單獨文件。若您需要更多語言，請聯絡技術支援。	zh-TW
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.com.tw/voice/tts"

# 查詢參數
params = {
    "key": "API_KEY",                # 替換為您的 API Key
    "secret": "API_SECRET",          # 替換為您的 API Secret
    "from": "+85299998888",          # 主叫號碼 (Caller ID)
    "to": "886912345678",            # 目標號碼
    "lang": "zh-TW",                 # 語言代碼
    "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.com.tw/voice/tts';

// 查詢參數
const params = {
    key: 'API_KEY',               // 替換為您的 API Key
    secret: 'API_SECRET',         // 替換為您的 API Secret
    from: '+85299998888',         // 主叫號碼 (Caller ID)
    to: '886912345678',           // 目標號碼
    lang: 'zh-TW',                // 語言代碼
    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.com.tw/voice/tts";

// 查詢參數
$params = [
    "key" => "API_KEY",             // 替換為您的 API Key
    "secret" => "API_SECRET",       // 替換為您的 API Secret
    "from" => "+85299998888",       // 主叫號碼 (Caller ID)
    "to" => "886912345678",         // 目標號碼
    "lang" => "zh-TW",              // 語言代碼
    "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.com.tw/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", "886912345678");          // 目標號碼
        urlBuilder.addQueryParameter("lang", "zh-TW");               // 語言代碼
        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.com.tw/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", "886912345678")           // 目標號碼
    params.Add("lang", "zh-TW")                // 語言代碼
    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()

    // 讀取回應體
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println("讀取回應出錯:", err)
        return
    }

    var result map[string]interface{}
    if err := 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）接收語音狀態報告，例如是否成功接通、播放時長等。請參見單獨文件：「語音信息狀態報告接收 API 」。

同時，也可登入 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：若需簡訊 + 語音訊息聯動，可參考簡訊 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. 附錄​