音声メッセージ API：テキスト音声合成 (TTS)

数行のシンプルなコードを使用するだけで、テキストコンテンツを音声メッセージ (TTS) に変換し、電話の形式で世界中のあらゆる地域の電話番号に送信できます。PaaSoo は現在、60 以上の言語の音声変換をサポートしており、多言語および多様なシナリオにおいて柔軟で信頼性の高い通話サービスを提供します。機能の有効化や、その他の高度な機能をご希望の場合は、テクニカルサポートまたはアカウントマネージャーまでご連絡ください。

1. 音声メッセージ API の概要

本音声メッセージ API（Voice Messaging API）は、テキストコンテンツを音声に変換した後、ターゲット番号に電話をかけてメッセージを再生します。適用されるシナリオは以下の通りです：

リアルタイムの OTP (ワンタイムパスワード) 音声読み上げ。
多言語のターゲット層にリーチするためのアナウンスやマーケティングメッセージ。
請求書の支払いや予約のリマインダーなどの自動通知により、電話形式で通知の到達率を向上。

注意：一部の国や地域では、特にマーケティング目的で使用する場合、音声通話に厳しい制限が設けられています。このような業務を展開する前に、現地の法規制を遵守していることを必ず確認してください。

2. 呼び出し方法

呼び出し方法

HTTP Method：GET
リクエスト URL：https://api.paasoo.jp/voice/tts

事前に key と secret を取得していることを確認し、呼び出し時にクエリパラメータ（QueryString）経由で渡してください。

3. リクエストのサンプル

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

サンプルの説明：

text パラメータ内の + と %2C は URL エンコードのサンプルであり、カンマ , は適度な一時停止に使用されます。
repeat=2 は、このメッセージの内容が 1 回の通話で連続して 2 回再生されることを示します。

4. リクエストパラメータの説明

パラメータ	型	必須	説明	サンプル
key	string	はい	API Key（英数字8桁）。アカウントの一意の識別子として使用します。PaaSoo の管理コンソールで取得できます。	Abcdefgh
secret	string	はい	API Secret（英数字8桁）。`key` と組み合わせて認証に使用します。PaaSoo の管理コンソールで取得できます。	Abc123EF
from	string	はい	発信元番号 (Caller ID)。`+` と数字、または数字のみの形式（最大 20 桁）をサポートします。カスタマイズが必要な場合はテクニカルサポートにご連絡ください。	+815012345678
to	string	はい	宛先番号。国番号を含みます。例えば、日本の番号 `09012345678` の国番号は `81` なので、`819012345678` と記述します。	819012345678
lang	string	はい	読み上げの言語コード。詳細は対応言語リストまたは個別のドキュメントをご参照ください。さらに多くの言語が必要な場合は、テクニカルサポートにご連絡ください。	ja-JP
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.jp/voice/tts"

# クエリパラメータ
params = {
    "key": "API_KEY",                # あなたの API Key に置き換えてください
    "secret": "API_SECRET",          # あなたの API Secret に置き換えてください
    "from": "+815012345678",         # 発信元番号 (Caller ID)
    "to": "819012345678",            # 宛先番号
    "lang": "ja-JP",                 # 言語コード
    "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.jp/voice/tts';

// クエリパラメータ
const params = {
    key: 'API_KEY',               // あなたの API Key に置き換えてください
    secret: 'API_SECRET',         // あなたの API Secret に置き換えてください
    from: '+815012345678',        // 発信元番号 (Caller ID)
    to: '819012345678',           // 宛先番号
    lang: 'ja-JP',                // 言語コード
    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.jp/voice/tts";

// クエリパラメータ
$params = [
    "key" => "API_KEY",             // あなたの API Key に置き換えてください
    "secret" => "API_SECRET",       // あなたの API Secret に置き換えてください
    "from" => "+815012345678",      // 発信元番号 (Caller ID)
    "to" => "819012345678",         // 宛先番号
    "lang" => "ja-JP",              // 言語コード
    "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.jp/voice/tts").newBuilder();
        urlBuilder.addQueryParameter("key", "API_KEY");              // あなたの API Key に置き換えてください
        urlBuilder.addQueryParameter("secret", "API_SECRET");        // あなたの API Secret に置き換えてください
        urlBuilder.addQueryParameter("from", "+815012345678");       // 発信元番号 (Caller ID)
        urlBuilder.addQueryParameter("to", "819012345678");          // 宛先番号
        urlBuilder.addQueryParameter("lang", "ja-JP");               // 言語コード
        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.jp/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", "+815012345678")        // 発信元番号 (Caller ID)
    params.Add("to", "819012345678")           // 宛先番号
    params.Add("lang", "ja-JP")                // 言語コード
    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 を解析
    body, err := ioutil.ReadAll(resp.Body)
    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）を通じて、正常に接続されたかどうか、再生時間などの音声ステータスレポートを受信できます。詳細については、個別のドキュメント『音声メッセージのステータスレポートの受信』をご参照ください。

また、PaaSoo 管理コンソールにログインして、通話レポートおよび詳細な記録を確認することも可能です。

10. ベストプラクティスとよくある質問

パラメータのセキュリティ：key と secret は厳重に管理し、バックエンドサーバーでのみ呼び出すようにしてください。
言語と方言：ユーザーの理解度と受容性を高めるために、適切な lang を選択してください。
メッセージの理解しやすさ：騒がしい環境では、一時停止時間を増やしたり、repeat 再生回数を設定したりする必要がある場合があります。
タイムゾーンと法律：現地の法的状況に注意し、デリケートな時間帯や法律で禁止されている時間帯での発信を避けてください。
費用と通話時間：音声サービスのコストは通常 SMS よりも高くなります。大量のアクティブな発信を行う前に、予算を評価し、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 + 音声メッセージの連携が必要な場合は、SMS API をご参照ください。現在、コンバージョントラッキング API は SMS にのみ適用され、音声メッセージ API には対応していません。

テクニカルサポート

API 連携の過程で技術的な問題やビジネスに関する疑問が生じた場合は、いつでも当社の開発者サポートチーム（support@paasoo.com）までご連絡ください。誠心誠意、技術的なサポートを提供いたします。

1. 音声メッセージ API の概要​

2. 呼び出し方法​

3. リクエストのサンプル​

4. リクエストパラメータの説明​

5. レスポンスパラメータの説明​

5.1 成功サンプル​

5.2 失敗サンプル​

6. 音声コンテンツパラメータの説明​

7. コードサンプル​

8. 対応言語リスト​

9. 音声メッセージのステータスレポートの受信​

10. ベストプラクティスとよくある質問​

11. よくある質問（FAQ）​

12. 付録​