/listenhub-tts

name: listenhub-tts
description: >
  使用 ListenHub API 将文本转换为语音（TTS）。支持三种模式：快速合成（/v1/tts）、
  多角色脚本（/v1/speech）、长文本流式合成（/v1/flow-speech/episodes）。
  音色未指定时自动获取音色列表供用户选择，默认使用 chat-girl-105-cn（晓曼）。
  Use when user says: "tts", "text to speech", "语音合成", "文字转语音", "朗读",
  "生成语音", "生成音频", "转音频", "text to audio"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - AskUserQuestion
user-invocable: true
metadata:
  trigger: TTS语音合成、text to speech、文字转语音、朗读文本、生成音频

ListenHub TTS: 文本转语音

使用 ListenHub OpenAPI 将文本转换为语音。支持三种合成模式，覆盖从短文本到长文本的全场景。

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 |

三种合成模式

模式一：快速合成（短文本，单音色）

**适用场景：** 短文本（< 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. 检查文本长度 > 100