メインコンテンツまでスキップ

Streaming TTS API

このページでは、Kotoba の ストリーミング Text-to-Speech（TTS） エンドポイントについて説明します。

認証​

すべてのリクエストに APIキー が必要です。

  • HTTP: Authorization: Bearer <KOTOBA_API_KEY>
  • ブラウザ / モバイルアプリのバンドルに APIキーを 埋め込まない でください。

Errors / error codes​

Kotoba API は構造化された error JSON を返します（サイドバーの Errors schema を参照）。

ストリーミング SSE の場合、致命的エラーは以下としても送られます。

  • event: error

TTS でよく見る error code:

  • invalid_api_key（HTTP 401）: APIキーが不正 / 未指定
  • rate_limit_exceeded / too_many_concurrent_requests（HTTP 429）: レート / 同時実行の制限
  • quota_exceeded: クレジット不足
  • invalid_parameters / bad_request（HTTP 400）: リクエストが不正
  • text_string_required（HTTP 422）: input が空 / 不正
  • max_character_length_exceeded: input が長すぎる
  • voice_not_found: voice が不正
  • audio_format_not_found: response_format が不正
  • language_not_found: language が不正

SSE による Streaming TTS（推奨）​

エンドポイント​

POST https://api.kotobatech.ai/v1/tts/sse

Request body（JSON）​

このリポジトリのリクエストモデルは TTSSSERequest / TTSRequest（サーバーサイド）です。

{
  "input": "Hello! This is a streaming TTS test.",
  "voice": "ja-man-1",
  "response_format": "pcm16",
  "language": "en"
}
  • input: 音声合成したいテキスト
  • voice: プリセット voice id（デフォルト: ja-man-1）
  • response_format: pcm16 | float32 | mulaw
  • language: ja | en

Response（Server-Sent Events）​

レスポンスは text/event-stream です。

  • event: delta: base64 の音声 chunk
  • event: done: ストリーム完了
  • event: error: エラーメッセージ

SSE payload の例:

event: delta
data: {"type":"speech.audio.delta","item_id":"...","delta":"<base64 audio bytes>"}

event: done
data: {"type":"speech.audio.done","item_id":"..."}

curl 例​

curl -N "https://api.kotobatech.ai/v1/tts/sse" \
  -H "Authorization: Bearer $KOTOBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello! This is a streaming TTS test.",
    "voice": "ja-man-1",
    "response_format": "pcm16",
    "language": "en"
  }'

WebSocket による Realtime TTS（experimental）​

エンドポイント​

wss://api.kotobatech.ai/v1/realtime_tts

全体の流れ​

  1. APIキー認証で WebSocket に接続します。
  2. サーバーイベント tts_session.created を待ちます。
  3. tts_session.update を 1回だけ 送って合成を開始します。
  4. tts.output.completed まで tts.output_audio.delta（base64 音声）を受信します。

Client → Server: tts_session.update​

{
  "type": "tts_session.update",
  "session": {
    "input_text": "Hello from realtime TTS.",
    "preset_voice": "ja_man_1",
    "output_audio_format": "pcm16",
    "output_audio_sample_rate": 24000,
    "output_audio_number_of_channels": 1,
    "language": "en"
  }
}

Server → Client events​

  • tts_session.created
  • tts_session.updated
  • tts.output_audio.delta（delta に base64 音声 bytes）
  • tts.output.completed