概要
Kotodamaでは、APIを通じたリアルタイム音声合成をサポートしています。このドキュメントでは、その使い方について説明します。
必要情報の準備
APIの利用には、(1) speaker_id, decoration_id、および、(2) API Keyが必要です。
まず、KotodamaのWeb画面からログインしてください。
その後、APIで利用したいキャラクターと言語・感情を選び、下画像の箇所から必要な情報をメモします。
speaker_idはキャラクターごとに設定されている名称です
decoration_idは、言語や感情ごとに設定されている名称です。英語の場合は、末尾に”_en”が付与されます。
次に、右上のマークから設定画面を開きます。
設定画面の下箇所をクリックし、表示されたAPI Keyをコピーします。
API Keyが流出すると、不正利用により思わぬ課金が発生する可能性があります。管理は厳重に行うようにしてください。
WebSocketでのリアルタイム呼び出し
リアルタイムに音声合成を行う場合、WebSocket経由のストリーミング形式で音声を送信する仕組みを利用します。
3つのステップで呼び出しを行います。
(1) ハンドシェイク
(2) 話者選択
(3) テキスト送信
基本的に、(1) ハンドシェイクは一回つなげたら以降は繋ぎっぱなし、(2) についてもspeaker_idやdecoration_idが変化したときだけ行い、それ以外の場合には(3)のみを繰り返し送ることで、余分なラグを発生させずに音声生成を行います。
(1) ハンドシェイク
接続先:
wss://tts3.spiral-ai-app.com/ws/tts
認証: HTTP ヘッダ
X-API-Key: <YOUR_API_KEY>
(YOUR_API_KEYは、上記で取得したもの)WebSocket接続を確立する際、HTTPヘッダに認証情報を含めます。
これで、WebSocketが接続されました。
以降は、すべてWebSocketのセッションで送受信する事項になります。
(2) 話者選択
type: "config"
メッセージで話者と音声スタイルを指定します。以下のような内容を送信します。
{
"type": "config",
"reference_mode": "sft",
"sft": {
"speaker_id": "Kukuri",
"decoration_id": "default"
}
}
パラメータ:
reference_mode
: "sft"
を指定sft.speaker_id
: 上記で取得したものsft.decoration_id
: 上記で取得したもの高度なパラメータ:
send_final_wav
: オプション（boolean）。 true
の場合、最終音声チャンクと共に完全なWAVファイル（base64エンコード）も送信されますexp_delay
: オプション。期待遅延時間の統計設定。このオプションは、ストリーミングで生成されるチャンクが、実際の再生に追いつかないということが起きないように、初期の待ち時間を推定するための設定です。percentile
: パーセンタイル値（50, 90, 95, 99など)。99の場合、99%の確度で遅延が発生しないような値を選びます。一般的には、50に設定する程度で十分な品質が得られます。time_period
: 統計期間（ "last_1min"
, "last_3min"
, "last_10min"
, など)。過去X分を見て、上記統計を計算します。応答
設定が正常に処理されると、サーバーから以下のメッセージが返されます：
{
"type": "ready"
}
このメッセージを受信したら、音声合成リクエストを送信できます。
(3) テキスト送信
type: "synthesis"
メッセージで合成するテキストを送信します。
{
"type": "synthesis",
"text": "こんにちは、世界。",
"is_last": true
}
パラメータ:
text
: 合成するテキストis_last
: 必ずtrue
を設定します。それをトリガとして、音声合成を開始します。音声受信
サーバーから
type: "audio"
メッセージとして音声データが送信されます。{
"type": "audio",
"data": {
"audio": "<base64エンコードされたPCMデータ>",
"chunk_id": 0,
"synthesis_id": "12345678-1234-1234-1234-123456789abc",
"audio_seconds": 0.5,
"is_last": false,
"exp_delay": 0.123
}
}
データフィールド:
audio
: base64エンコードされたPCM音声データ（24kHz, モノラル, float32）chunk_id
: チャンク番号（0から開始）synthesis_id
: 合成セッションのユニークID（UUID）audio_seconds
: このチャンクの音声の長さ（秒）is_last
: 最後のチャンクの場合 true
exp_delay
: 最初のチャンクのみ付与される期待遅延時間（秒）
最終チャンクの受信
最後のチャンクには追加情報が含まれます：
{
"type": "audio",
"data": {
"audio": "<base64エンコードされたPCMデータ>",
"chunk_id": 5,
"synthesis_id": "12345678-1234-1234-1234-123456789abc",
"audio_seconds": 0.3,
"is_last": true,
"total_audio_seconds": 2.5,
"total_chunks": 6,
"wav": "<base64エンコードされたWAVファイル（オプション）>"
}
}
追加フィールド（最終チャンクのみ）:
total_audio_seconds
: 合計音声時間（秒）total_chunks
: 合計チャンク数wav
: send_final_wav: true
の場合のみ、完全なWAVファイル（base64エンコード、PCM_16, 24kHz, モノラル）
PCMデータのデコード
受信したPCMデータは以下の仕様です：
サンプルレート: 24,000 Hz
チャンネル数: 1（モノラル）
フォーマット: float32（リトルエンディアン）
サンプルコード
python
Node.js
FAQ
接続できない
APIキーが正しいか確認してください
ネットワーク環境がWebSocket接続を許可しているか確認してください
ready
が返ってこないspeaker_id
と decoration_id
が正しいか確認してくださいreference_mode
が "sft"
または "zero_shot"
であることを確認してください音声が途切れる
ネットワークの帯域を確認してください
exp_delay
フィールドを参考に、バッファリングを調整してください`
REST APIでの呼び出し
仕様
テキストから音声を合成します。
エンドポイント:
https://tts3.spiral-ai-app.com/api/tts_generate
認証: HTTP ヘッダ
X-API-Key: <YOUR_API_KEY>
(YOUR_API_KEYは、上記で取得したもの)
リクエスト例
curl -X POST "https://tts3.spiral-ai-app.com/api/tts_generate" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"text": "こんにちは、音声合成のテストです。聞こえていますか？",
"speaker_id": "Kukuri",
"decoration_id": "neutral",
"audio_format": "wav"
}'
text
(string): 必須。合成するテキストspeaker_id
(string): 必須decoration_id
(string): 必須audio_format
(string): 出力フォーマット { ”wav”
, "ogg"
, "mp3"
}レスポンス例
{
"audios": [
"UklGRiQAAABXQVZFZm10IBAAAAABAAEARKwAAIhYAQACABAAZGF0YQAAAAA="
],
"durations": [2.34],
"total_audio_seconds": 2.34,
"synthesis_id": "c0a1b2c3-04d5-6789-0abc-1de2f3a4b5c6"
}
audios
: Base64エンコードされた音声データの配列durations
: 各音声の長さ（秒）total_audio_seconds
: 合計音声時間synthesis_id
: 合成リクエストの一意識別子
出力音声仕様
フォーマット: WAV (RIFF) / OGG (Vorbis) / MP3
エンコーディング: PCM 16-bit (WAVの場合)
サンプルレート: 24,000 Hz
チャンネル: 1 (モノラル)
