listenhub-tts

ListenHub TTS：テキスト読み上げ

ListenHub OpenAPI を使用して、テキストを音声に変換します。3 種類の合成モードに対応し、短文から長文まで、あらゆるケースをカバーします。

API 情報

• Base URL: https://api.marswave.ai/openapi
• 認証: Authorization: Bearer $LISTENHUB_API_KEY（環境変数から読み込みます）
• 事前確認: API を呼び出す前に、LISTENHUB_API_KEY 環境変数が設定されていることを必ず確認してください。設定されていない場合は、ユーザーに設定を促してください。

音声の選択手順

ユーザーが音声を明示的に指定している場合

ユーザーが指定した speakerId をそのまま使用し、選択手順をスキップします。

ユーザーが音声を指定していない場合

1. GET /v1/speakers/list?language=zh を呼び出して、利用可能な音声の一覧を取得します
2. AskUserQuestion を使用して、以下の形式で音声の一覧を表示し、ユーザーに選択してもらいます：
   • デフォルトでは chat-girl-105-cn（晓曼 dxqqq）を選択します
   • 一覧の表示形式：{name}（{gender}，{speakerId}）
   • 参考用に各音声の demoAudioUrl を添えます
3. ユーザーの確認後、選択した speakerId を使用します

デフォルトの音声

フィールド	値
speakerId	chat-girl-105-cn
名前	晓曼 dxqqq

3 種類の合成モード

モード一：高速合成（短文、単一音声）

適用シーン： 短文（< 1000 字）、単一音声、低レイテンシが必要な場合

インターフェース： POST /v1/tts

リクエストボディ：

{
  "text": "要合成的文本",
  "speakerId": "chat-girl-105-cn",
  "format": "mp3",
  "sampleRate": 24000,
  "speed": 1.0
}

パラメーター	型	必須	説明
text	string	はい	合成するテキスト
speakerId	string	はい	音声 ID
format	string	いいえ	出力形式。デフォルトは mp3
sampleRate	int	いいえ	サンプルレート。デフォルトは 24000
speed	float	いいえ	読み上げ速度。デフォルトは 1.0、範囲は 0.5 ~ 2.0

レスポンス： MP3 バイナリストリームを直接返します（Content-Type: audio/mpeg）

呼び出し例：

curl -X POST "https://api.marswave.ai/openapi/v1/tts" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "你好世界", "speakerId": "chat-girl-105-cn"}' \
  -o output.mp3

モード二：複数の役割によるスクリプト合成

適用シーン： 複数の役割による会話、ポッドキャスト、オーディオブックの一部など、異なる音声を切り替えて読み上げる場合

インターフェース： POST /v1/speech

リクエストボディ：

{
  "script": [
    {
      "text": "你好，欢迎收听本期节目。",
      "speakerId": "chat-girl-105-cn"
    },
    {
      "text": "谢谢，今天我们来聊聊 AI。",
      "speakerId": "chat-boy-101-cn"
    }
  ],
  "format": "mp3",
  "sampleRate": 24000
}

パラメーター	型	必須	説明
script	array	はい	スクリプトの配列。各項目には text と speakerId が含まれます
script[].text	string	はい	該当部分のテキスト
script[].speakerId	string	はい	該当部分の音声 ID
format	string	いいえ	出力形式。デフォルトは mp3
sampleRate	int	いいえ	サンプルレート。デフォルトは 24000

レスポンス： JSON

{
  "audioUrl": "https://cdn.example.com/output.mp3",
  "duration": 12.5
}

呼び出し例：

curl -X POST "https://api.marswave.ai/openapi/v1/speech" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": [
      {"text": "你好，欢迎收听。", "speakerId": "chat-girl-105-cn"},
      {"text": "谢谢，我们开始吧。", "speakerId": "chat-boy-101-cn"}
    ]
  }'

モード三：長文のストリーミング合成

適用シーン： 長文（> 1000 字）、記事の読み上げ、AI による推敲や分割処理が必要な場合

インターフェース： POST /v1/flow-speech/episodes

リクエストボディ：

{
  "title": "文章标题",
  "content": "长文本内容...",
  "speakerId": "chat-girl-105-cn",
  "mode": "direct",
  "format": "mp3"
}

パラメーター	型	必須	説明
title	string	はい	音声のタイトル
content	string	いいえ	テキスト内容（contentUrl とのいずれか一方を指定）
contentUrl	string	いいえ	コンテンツ URL（content とのいずれか一方を指定）
speakerId	string	はい	音声 ID
mode	string	いいえ	direct（直接合成）または aiPolish（AI による推敲）。デフォルトは direct
format	string	いいえ	出力形式。デフォルトは mp3

レスポンス： JSON

{
  "episodeId": "ep_abc123",
  "status": "processing"
}

ポーリングによる結果の取得：

GET /v1/flow-speech/episodes/{episodeId}

ポーリング方針：

1. 送信後、30 秒待ちます
2. 以降は 10 秒ごとにポーリングします
3. status が completed または failed になるまで続けます

ポーリングレスポンス：

{
  "episodeId": "ep_abc123",
  "status": "completed",
  "audioUrl": "https://cdn.example.com/output.mp3",
  "duration": 180.5
}

status 値	説明
processing	合成中です。ポーリングを続けてください
completed	合成が完了しました。audioUrl を使用できます
failed	合成に失敗しました。errorMessage を確認してください

呼び出し例：

# 提交任务
curl -X POST "https://api.marswave.ai/openapi/v1/flow-speech/episodes" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI 技术趋势",
    "content": "长文本内容...",
    "speakerId": "chat-girl-105-cn",
    "mode": "direct"
  }'

# 轮询结果
curl "https://api.marswave.ai/openapi/v1/flow-speech/episodes/ep_abc123" \
  -H "Authorization: Bearer $LISTENHUB_API_KEY"

音声一覧の取得

インターフェース： GET /v1/speakers/list

クエリパラメーター：

パラメーター	型	必須	説明
language	string	いいえ	言語で絞り込みます。例：zh（中国語）、en（英語）

レスポンス：

{
  "speakers": [
    {
      "name": "晓曼 dxqqq",
      "speakerId": "chat-girl-105-cn",
      "demoAudioUrl": "https://cdn.example.com/demo.mp3",
      "gender": "female",
      "language": "zh"
    }
  ]
}

モードの選択ロジック

ユーザーの入力に基づいて、最適なモードを自動的に選択します：

条件	モード
テキスト ≤ 1000 字、単一音声	モード一：/v1/tts
複数の役割によるスクリプトで、異なる音声が必要	モード二：/v1/speech
テキスト > 1000 字、または AI による推敲が必要	モード三：/v1/flow-speech/episodes
ユーザーがコンテンツソースとして URL を指定	モード三：/v1/flow-speech/episodes

ユーザーがモードを明示的に指定した場合は、その指定を優先します。

ユーザーとのやり取り

音声の選択

ユーザーが音声を指定していない場合は、AskUserQuestion を使用して音声の一覧を表示します：

请选择音色（默认：晓曼 dxqqq）：
A. 晓曼 dxqqq（女，chat-girl-105-cn）[默认]
B. [其他音色名称]（[性别]，[speakerId]）
C. ...

合成パラメーター

必要に応じて、以下を確認できます：

• 読み上げ速度 speed（デフォルトは 1.0）
• 出力形式 format（デフォルトは mp3）
• 長文モード：direct または aiPolish（デフォルトは direct）
• 出力ファイルパス（デフォルトは ./output.mp3）

出力

1. 音声を指定されたパスに保存します（デフォルトは ./output.mp3）
2. 以下の合成概要を出力します：
   • 使用したモード
   • 音声の名前と ID
   • 音声の長さ
   • ファイルサイズ
   • ファイルパス

エラー処理

• 401 Unauthorized: LISTENHUB_API_KEY 環境変数を確認するようユーザーに促します
• 400 Bad Request: リクエストパラメーターを確認し、具体的なエラーをユーザーに報告します
• flow-speech failed: errorMessage を報告し、再試行またはモードの切り替えを提案します
• ネットワークエラー: ネットワーク接続の確認を促し、再試行を提案します

完全な例

ユーザー入力： 「次のテキストを音声に変換してください：今日はとてもいい天気なので、散歩に出かけるのにぴったりです。」

実行手順：

1. LISTENHUB_API_KEY を確認 ✓
2. テキストの長さが 1000 字未満で単一音声のため、モード一 /v1/tts を選択
3. ユーザーが音声を指定していないため、デフォルトの chat-girl-105-cn（晓曼）を使用
4. API を呼び出して合成
5. ./output.mp3 に保存
6. 概要を出力

ユーザー入力： 「晓曼の声で、この記事を読み上げてください：article.md」

実行手順：

1. article.md の内容を読み込みます
2. テキストの長さが 1000 字を超えることを確認し、モード三 /v1/flow-speech/episodes を選択します
3. 音声は指定済みです：chat-girl-105-cn（晓曼）
4. 合成タスクを送信します
5. 完了するまでポーリングします
6. 音声をダウンロードし、./article.mp3 に保存します
7. 概要を出力します