Mybooks tts

MyBooks(PoxenStudio/Talebook)的MiMo TTS有声书工具，支持将EPUB电子书转换为有声书。你可以帮助用户：配置TTS API（MiMo或OpenAI兼容）、测试API连接、开始EPUB转有声书、查询转换进度、管理克隆音色库（上传/列表/删除/试听）、管理自定义语音提示词库（保存/列表/删除）等。所有操作需要管理员权限。

shiningsprk-arch@shiningsprk-arch

Install

openclaw skills install @shiningsprk-arch/mybooks-tts

MyBooks TTS (MiMo TTS 有声书工具)

Requirements

bash

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

然后按如下方式执行：
<skill-installation-path>/scripts/mybooks_tts_api.py <tool-name> '<json-args>'

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

通用响应格式与认证方式

通用 JSON 响应结构

所有 API 均返回如下格式：

json

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

常见错误码：

`err` 值	含义
`"ok"`	操作成功
`"user.need_login"`	未登录或登录态已过期
`"permission"`	无权限（需管理员）
`"params.invalid"`	请求参数错误
`"params.book.invalid"`	书籍不存在或 ID 错误
`"task.running"`	后台任务正在进行中，稍后重试
`"tts.converting"`	TTS 转换任务正在运行
`"tts.no_config"`	未配置 API
`"clone.exists"`	克隆音色名称已存在
`"clone.not_found"`	克隆音色不存在
`"clone.too_large"`	文件超过 7MB 限制
`"clone.invalid_format"`	仅支持 MP3/WAV 格式
`"prompt.exists"`	提示词名称已存在
`"prompt.not_found"`	提示词不存在

认证方式

脚本通过 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、模型、密钥、类型等），保存后服务端加密存储

权限：管理员

参数：

参数	类型	必填	说明
`api_url`	string	✅	API 地址，如 `https://api.xiaomimimo.com/v1/chat/completions`
`model_name`	string	✅	模型 ID，MiMo TTS 类型固定为 `mimo-v2.5-tts`
`api_type`	string	✅	API 类型：`chat_completions`（MiMo TTS）/ `audio_speech`（OpenAI 兼容）/ `custom`
`api_key`	string	✅	API 密钥
`auth_type`	string	❌	认证类型：`bearer`（默认）/ `basic` / `custom`
`voice_name`	string	❌	预置音色 ID（`api_type=chat_completions` 且 `voiceType=preset` 时）或 `audio_speech` 的音色名
`voice_desc`	string	❌	自定义音色描述（`voiceType=custom` 时）
`clone_voice`	string	❌	克隆音色名称（`voiceType=clone` 时）

执行脚本：

bash

<skill-installation-path>/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"}'

响应示例：

json

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

`tts_test_connection` — 测试 API 连接

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

权限：管理员

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

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_test_connection '{}'

响应示例：

json

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

常见错误：

`err` 值	含义
`"tts.no_config"`	未保存配置，请先调用 `tts_save_config`
`"tts.connection_failed"`	无法连接到 API 服务器
`"tts.invalid_key"`	API Key 无效

`tts_convert` — 开始 EPUB 转有声书

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

权限：管理员

参数：

参数	类型	必填	说明
`book_id`	int	✅	书籍 ID
`api_url`	string	✅	API 地址
`model_name`	string	✅	模型 ID
`api_type`	string	✅	API 类型：`chat_completions` / `audio_speech` / `custom`
`api_key`	string	✅	API 密钥
`auth_type`	string	❌	认证类型（默认 `bearer`）
`voice_name`	string	❌	预置音色 ID 或 `audio_speech` 音色名
`voice_desc`	string	❌	自定义音色描述
`clone_voice`	string	❌	克隆音色名称

执行脚本：

bash

<skill-installation-path>/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"}'

响应示例：

json

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

常见错误：

`err` 值	含义
`"params.book.invalid"`	书籍不存在
`"tts.converting"`	已有转换任务在运行
`"book.no_epub"`	书籍没有 EPUB 格式

`tts_progress` — 查询转换进度

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

权限：管理员

参数：无

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_progress '{}'

响应示例：

json

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

status 值：

值	含义
`"idle"`	无任务运行
`"running"`	转换进行中
`"completed"`	转换已完成
`"failed"`	转换失败

`tts_clone_upload` — 上传克隆音色

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

权限：管理员

参数：

参数	类型	必填	说明
`voice_name`	string	✅	克隆音色名称（如"旁白"、"男主"）
`file_path`	string	✅	本地音频文件的绝对路径（MP3/WAV，≤7MB）

限制：

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

执行脚本：

bash

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

响应示例：

json

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

常见错误：

`err` 值	含义
`"clone.exists"`	音色名称已存在
`"clone.too_large"`	文件超过 7MB
`"clone.invalid_format"`	格式不支持

`tts_clone_list` — 克隆音色列表

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

权限：管理员

参数：无

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_clone_list '{}'

响应示例：

json

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

`tts_clone_delete` — 删除克隆音色

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

权限：管理员

参数：

参数	类型	必填	说明
`voice_name`	string	✅	要删除的克隆音色名称

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_clone_delete '{"voice_name":"旁白"}'

响应示例：

json

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

`tts_clone_audio` — 下载克隆音频

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

权限：管理员

参数：

参数	类型	必填	说明
`voice_name`	string	✅	克隆音色名称
`save_to`	string	❌	保存到本地路径（不传则返回 base64）

执行脚本：

bash

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

# 返回 base64（小文件）
<skill-installation-path>/scripts/mybooks_tts_api.py tts_clone_audio '{"voice_name":"旁白"}'

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

json

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

`tts_prompt_list` — 提示词列表

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

权限：管理员

参数：无

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_prompt_list '{}'

响应示例：

json

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

`tts_prompt_save` — 保存提示词

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

权限：管理员

参数：

参数	类型	必填	说明
`name`	string	✅	提示词名称
`desc`	string	✅	音色描述（自然语言描述语音特征）

执行脚本：

bash

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

响应示例：

json

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

`tts_prompt_delete` — 删除提示词

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

权限：管理员

参数：

参数	类型	必填	说明
`name`	string	✅	要删除的提示词名称

执行脚本：

bash

<skill-installation-path>/scripts/mybooks_tts_api.py tts_prompt_delete '{"name":"温柔女声"}'

响应示例：

json

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

使用场景决策指南

text

用户请求
│
├─ "配置 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 个预置音色：

ID	名称	语言	性别
`mimo_default`	MiMo-默认	中文	女
`冰糖`	冰糖	中文	女
`茉莉`	茉莉	中文	女
`苏打`	苏打	中文	男
`白桦`	白桦	中文	男
`Mia`	Mia	英文	女
`Chloe`	Chloe	英文	女
`Milo`	Milo	英文	男
`Dean`	Dean	英文	男

错误处理规范

`err` 值	含义	建议处理
`"ok"`	操作成功	展示结果
`"user.need_login"`	未登录	脚本自动重登录，仍失败则检查环境变量
`"permission"`	非管理员	说明当前账号权限不足
`"params.book.invalid"`	书籍不存在	建议用搜索确认 book_id
`"task.running"` / `"tts.converting"`	任务进行中	等待完成后重试
`"tts.no_config"`	未配置	先调用 `tts_save_config`
`"clone.too_large"`	文件超限	提示用户裁剪音频至 7MB 内
`"clone.invalid_format"`	格式不支持	仅支持 MP3/WAV
`"clone.exists"`	名称重复	换名或先删除旧的

注意事项

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

Mybooks tts

Install

MyBooks TTS (MiMo TTS 有声书工具)

Requirements

通用响应格式与认证方式

通用 JSON 响应结构

认证方式

工具列表

tts_save_config — 保存 TTS API 配置

tts_test_connection — 测试 API 连接

tts_convert — 开始 EPUB 转有声书

tts_progress — 查询转换进度

tts_clone_upload — 上传克隆音色

tts_clone_list — 克隆音色列表

tts_clone_delete — 删除克隆音色

tts_clone_audio — 下载克隆音频

tts_prompt_list — 提示词列表

tts_prompt_save — 保存提示词

tts_prompt_delete — 删除提示词

使用场景决策指南

预置音色参考

错误处理规范

注意事项

Related skills

`tts_save_config` — 保存 TTS API 配置

`tts_test_connection` — 测试 API 连接

`tts_convert` — 开始 EPUB 转有声书

`tts_progress` — 查询转换进度

`tts_clone_upload` — 上传克隆音色

`tts_clone_list` — 克隆音色列表

`tts_clone_delete` — 删除克隆音色

`tts_clone_audio` — 下载克隆音频

`tts_prompt_list` — 提示词列表

`tts_prompt_save` — 保存提示词

`tts_prompt_delete` — 删除提示词