Mybooks tts

MyBooks TTS (MiMo TTS 有声书工具)

Requirements

# 需要配置以下环境变量后方可使用
export MYBOOKS_HOST="http://127.0.0.1:8082"
export MYBOOKS_USER="admin"
export MYBOOKS_PASSWORD="your_password"
export MYBOOKS_SSL_VERIFY="false"   # 如服务器使用自签名证书，设为 false

然后按如下方式执行：
/scripts/mybooks_tts_api.py  ''

安全提示：请勿将凭据写入共享或全局配置文件（如 ~/.openclaw/.env），以避免凭据被其他 agent 或进程意外读取。建议通过会话级环境变量或专用密钥管理工具传入凭据。

通用响应格式与认证方式

通用 JSON 响应结构

所有 API 均返回如下格式：

{
  "err": "ok",       // "ok" 表示成功，其他字符串表示错误码
  "msg": "...",      // 可选，人类可读的成功/错误说明
  "data": { }        // 可选，具体响应数据（因接口而异）
}

常见错误码：

认证方式

• 脚本通过 MYBOOKS_USER / MYBOOKS_PASSWORD 环境变量自动调用 /api/user/sign_in 完成登录
• 服务端通过 Secure Cookie（user_id + lt）维持会话
• 若响应中出现 err=user.need_login，脚本会自动重新登录后重试一次；仍失败则报错退出
• 必须在调用前配置 MYBOOKS_HOST、MYBOOKS_USER、MYBOOKS_PASSWORD 三个环境变量，否则脚本直接报错退出
• 所有 TTS 接口均需要管理员权限

---

工具列表

tts_save_config — 保存 TTS API 配置

使用场景：配置 TTS API 的连接参数（API URL、模型、密钥、类型等），保存后服务端加密存储

权限：管理员

参数：

执行脚本：

/scripts/mybooks_tts_api.py tts_save_config '{"api_url":"https://api.xiaomimimo.com/v1/chat/completions","model_name":"mimo-v2.5-tts","api_type":"chat_completions","api_key":"sk-xxx","voice_name":"mimo_default"}'

响应示例：

{
  "err": "ok",
  "msg": "配置已保存"
}

---

tts_test_connection — 测试 API 连接

使用场景：使用当前保存的配置发送一次测试请求，验证 API Key 和端点是否可用

权限：管理员

参数：无（使用已保存的配置）

执行脚本：

/scripts/mybooks_tts_api.py tts_test_connection '{}'

响应示例：

{
  "err": "ok",
  "msg": "连接成功"
}

常见错误：

---

tts_convert — 开始 EPUB 转有声书

使用场景：将指定 EPUB 电子书转换为有声书，后台逐章合成 WAV 音频

权限：管理员

参数：

执行脚本：

/scripts/mybooks_tts_api.py tts_convert '{"book_id":42,"api_url":"https://api.xiaomimimo.com/v1/chat/completions","model_name":"mimo-v2.5-tts","api_type":"chat_completions","api_key":"sk-xxx","voice_name":"mimo_default"}'

响应示例：

{
  "err": "ok",
  "msg": "转换任务已启动"
}

常见错误：

---

tts_progress — 查询转换进度

使用场景：查询当前 TTS 转换任务的进度、阶段和章节信息

权限：管理员

参数：无

执行脚本：

/scripts/mybooks_tts_api.py tts_progress '{}'

响应示例：

{
  "err": "ok",
  "status": "running",
  "progress": 35,
  "stage": "converting",
  "current_chapter": 7,
  "total_chapters": 20,
  "current_title": "第七章 归途",
  "book_id": 42
}

status 值：

---

tts_clone_upload — 上传克隆音色

使用场景：上传 MP3/WAV 音频样本作为克隆音色，上传后自动切换到 mimo-v2.5-tts-voiceclone 模型

权限：管理员

参数：

限制：

• 格式：仅支持 .mp3 和 .wav
• 大小：原始文件 ≤ 7MB（Base64 编码后约 9.3MB，MiMo 官方限制 Base64 ≤ 10MB）

执行脚本：

/scripts/mybooks_tts_api.py tts_clone_upload '{"voice_name":"旁白","file_path":"/path/to/sample.mp3"}'

响应示例：

{
  "err": "ok",
  "msg": "克隆音色上传成功",
  "data": { "name": "旁白", "ext": "mp3", "size": 1048576 }
}

常见错误：

---

tts_clone_list — 克隆音色列表

使用场景：获取所有已上传的克隆音色列表

权限：管理员

参数：无

执行脚本：

/scripts/mybooks_tts_api.py tts_clone_list '{}'

响应示例：

{
  "err": "ok",
  "clones": [
    { "name": "旁白", "ext": "mp3", "size": 1048576 },
    { "name": "男主", "ext": "wav", "size": 2097152 }
  ]
}

---

tts_clone_delete — 删除克隆音色

使用场景：删除指定的克隆音色

权限：管理员

参数：

执行脚本：

/scripts/mybooks_tts_api.py tts_clone_delete '{"voice_name":"旁白"}'

响应示例：

{
  "err": "ok",
  "msg": "克隆音色已删除"
}

---

tts_clone_audio — 下载克隆音频

使用场景：下载/试听指定的克隆音色原始音频文件（返回二进制 WAV 数据）

权限：管理员

参数：

执行脚本：

# 保存到文件
/scripts/mybooks_tts_api.py tts_clone_audio '{"voice_name":"旁白","save_to":"/tmp/clone_preview.wav"}'

# 返回 base64（小文件）
/scripts/mybooks_tts_api.py tts_clone_audio '{"voice_name":"旁白"}'

响应示例（保存到文件）：

{
  "err": "ok",
  "msg": "音频已保存",
  "path": "/tmp/clone_preview.wav",
  "size": 1048576
}

---

tts_prompt_list — 提示词列表

使用场景：获取所有已保存的自定义语音提示词

权限：管理员

参数：无

执行脚本：

/scripts/mybooks_tts_api.py tts_prompt_list '{}'

响应示例：

{
  "err": "ok",
  "prompts": [
    { "name": "温柔女声", "desc": "温柔细腻的语调，语速偏慢，咬字清晰" },
    { "name": "沉稳男声", "desc": "沉稳厚重的语调，语速适中偏低" }
  ]
}

---

tts_prompt_save — 保存提示词

使用场景：将自定义音色描述保存为提示词（同名覆盖），存储于服务端 voice_prompts.json

权限：管理员

参数：

执行脚本：

/scripts/mybooks_tts_api.py tts_prompt_save '{"name":"温柔女声","desc":"温柔细腻的语调，语速偏慢，咬字清晰，富有亲和力"}'

响应示例：

{
  "err": "ok",
  "msg": "提示词已保存"
}

---

tts_prompt_delete — 删除提示词

使用场景：删除指定的语音提示词

权限：管理员

参数：

执行脚本：

/scripts/mybooks_tts_api.py tts_prompt_delete '{"name":"温柔女声"}'

响应示例：

{
  "err": "ok",
  "msg": "提示词已删除"
}

---

使用场景决策指南

用户请求
│
├─ "配置 TTS API" / "设置 MiMo API Key"
│   → tts_save_config
│
├─ "测试 API 能不能用" / "连接正常吗"
│   → tts_test_connection
│
├─ "把这本书转成有声书" / "开始转换"
│   → tts_convert（需先有配置或直接传参）
│
├─ "转换到哪了" / "进度怎么样"
│   → tts_progress
│
├─ "上传克隆音色" / "我想用自己的声音"
│   → tts_clone_upload
│
├─ "有哪些克隆音色" / "看看上传的音色"
│   → tts_clone_list
│
├─ "删除克隆音色" / "不要这个音色了"
│   → tts_clone_delete
│
├─ "试听克隆音色" / "下载克隆音频"
│   → tts_clone_audio
│
├─ "有哪些提示词" / "保存的音色描述"
│   → tts_prompt_list
│
├─ "保存这个音色描述" / "存一个提示词"
│   → tts_prompt_save
│
└─ "删除提示词" / "不要这个描述了"
    → tts_prompt_delete

---

预置音色参考

MiMo TTS 类型（api_type=chat_completions）内置 9 个预置音色：

---

错误处理规范

---

注意事项

1. 管理员权限：所有 TTS 接口均需要管理员权限，普通用户无法使用。
2. 异步转换：tts_convert 启动后台任务后立即返回，需用 tts_progress 轮询进度。
3. 断点续传：重复转换同一本书时，自动跳过已存在的 WAV 文件（≥44 字节），中断后可继续。
4. 音频输出：转换完成后，音频输出到 /audio/{book_id} 页面播放，也可通过 Web 界面访问。
5. 克隆音色限制：MP3/WAV ≤ 7MB；上传后自动切换 mimo-v2.5-tts-voiceclone 模型。
6. 提示词存储：提示词保存在服务端 voice_prompts.json，跨浏览器共享，不依赖本地存储。
7. API Key 加密：API Key 经 PBKDF2-SHA256 + 流加密保存，密钥文件权限 0o600。
8. 模型锁定：MiMo TTS 类型下模型 ID 固定为 mimo-v2.5-tts，不可修改；audio_speech 和 custom 类型可自由修改。