项目简介：基于小米MiMo Token‑Plan，使用PHP + FoxUI实现本地网页调试工具，实现预置音色TTS、方言/唱歌标签、音色克隆、音色设计完整能力。 ⚠️重要协议提醒：Token‑Plan仅限本地个人学习调试，禁止公网对外中转API服务，否则
tp‑开头的token会被封禁；TTS系列模型限时免费，不消耗套餐Credits。
一、项目功能
- 预置音色语音合成：官方全部预置音色，支持方言标签
(东北话)、(粤语)、(四川话)，情绪标签(温柔)、(御姐音)、(夹子音)，以及特殊(唱歌)唱歌模式。 - 音色克隆 voiceclone：上传mp3/wav人声样本；PC端浏览器录音，前端lamejs把webm转mp3后用于克隆。
- 音色设计 voicedesign：通过自然语言描述，生成全新自定义音色。
- UI：FoxUI前端框架，多Tab界面，音频预览、MP3下载。
- 配套工具：
setup.php配置保存tp‑key；debug‑api‑response.php接口调试页面。 - 后端：PHP curl调用MiMo Token‑Plan接口，支持JSON模式、文件FormData上传模式，内置调试日志输出。
Token‑Plan国内集群接口地址，不要使用普通mimo域名
https://token‑plan‑cn.xiaomimimo.com/v1/chat/completions
二、核心踩坑总结（重点）
坑1：不要套用OpenAI TTS思维，接口路径完全不一样
OpenAI TTS接口：/audio/speech，直接返回二进制音频。 小米MiMo‑V2.5 TTS复用chat/completions对话接口。 请求结构要点：
model指定模型；messages[0].role:user，messages[1].role:assistant，待合成文本写在assistant.content；audio对象配置format、voice；- 返回不是二进制MP3，返回JSON；音频数据在
choices[0].message.audio.data的base64字符串，PHP解码后输出二进制音频。
坑2：鉴权头不要用 Authorization: Bearer
Token‑Plan的tp‑token，官方推荐请求头： api‑key: tp‑xxxxxx 部分环境下Bearer鉴权会直接返回401鉴权失败。
坑3：音色克隆反复报错 Param Incorrect 参数错误（最耗时大坑）
- ❌错误：前端直接把大音频base64塞进JSON的fetch请求体
浏览器抛出：
Failed to execute 'fetch' on 'Window': Failed to read the 'headers' property from 'RequestInit': String contains non ISO‑8859‑1 code point.解决：前端不做base64编码，使用FormData上传原始二进制文件，PHP后端读取临时文件再做base64编码。 - ❌错误：浏览器录音输出webm格式，voiceclone模型不识别webm，直接报Param Incorrect
PC端折中方案：前端引入
lamejs，webm解码编码输出标准mp3 Blob再提交后端。 - ❌错误：
audio.voice参数格式混淆
音色克隆必须完整
data:audio/mpeg;base64,xxxxdata‑URI完整前缀，不能只传裸base64字符串。 PHP后端读取上传文件二进制，拼接完整前缀再传给小米API。 - ❌样本音频本身问题：不能带背景音乐、不能过长，首尾不要大量静音，建议5‑25秒干净人声。
坑4：三个模型能力不能混用
| 模型 | 能力 | 限制 |
|---|---|---|
mimo‑v2.5‑tts |
预置音色、方言标签、(唱歌)标签 |
不支持克隆、音色设计 |
mimo‑v2.5‑tts‑voiceclone |
音色克隆，上传音频样本 | 不支持唱歌标签；样本格式仅mp3/wav；文件≤10MB |
mimo‑v2.5‑tts‑voicedesign |
文字描述生成音色 | 不支持唱歌标签，voice字段不生效，音色描述放在user角色content |
坑5：移动端浏览器录音兼容性大坑
现象：手机可以获取麦克风权限，可以录音、audio播放器可以播放录音，但是前端转码会失败，无法用于音色克隆。
- iOS Safari录音输出是
m4a(AAC)格式； - 部分安卓浏览器输出特殊编码webm‑opus；
audio标签可以播放 ≠ AudioContext.decodeAudioData可以解码；播放器和解码API能力不一致；
现状：本项目PC浏览器录音+转mp3可用；手机端录音仅可以预览，不能直接提交克隆；手机想要克隆需要手动上传mp3/wav音频文件。
坑6 PHP环境配置，文件上传、超时
php.ini关键配置
file_uploads = On
upload_max_filesize = 12M
post_max_size = 14M
max_execution_time = 120
memory_limit = 256M
坑7 环境协议约束
- 浏览器录音：
localhost本地可以直接使用；公网部署必须HTTPS，http协议拿不到麦克风权限。 - Token‑Plan协议：仅限本地个人学习，禁止公网对外做中转API服务，会导致tp‑key封禁。
三、关键请求体示例
1、预置音色TTS
{
"model":"mimo‑v2.5‑tts",
"messages":[
{"role":"user","content":""},
{"role":"assistant","content":"你好，测试语音合成。"}
],
"audio":{
"format":"mp3",
"voice":"冰糖"
}
}
2、音色克隆请求体
{
"model":"mimo‑v2.5‑tts‑voiceclone",
"messages":[
{"role":"user","content":""},
{"role":"assistant","content":"你好，克隆声音测试"}
],
"audio":{
"format":"mp3",
"voice":"data:audio/mpeg;base64,*****完整mp3 base64*****"
}
}
3、音色设计请求体
{
"model":"mimo‑v2.5‑tts‑voicedesign",
"messages":[
{"role":"user","content":"一位温柔磁性中年女声，语速缓慢，适合讲故事"},
{"role":"assistant","content":"你好，测试音色设计"}
],
"audio":{
"format":"mp3"
}
}
四、PHP后端核心片段：音色克隆处理上传文件
//读取上传临时文件
$fileBin = file_get_contents($uploadFile['tmp_name']);
$pureB64 = base64_encode($fileBin);
//⚠️必须拼接完整data‑URI前缀
$cloneAudioFullDataUri = 'data:audio/mpeg;base64,' . $pureB64;
$requestData = [
'model' => $model,
'messages' => [
["role"=>"user","content"=>""],
["role"=>"assistant","content"=>$text]
],
'audio' => [
"format" => $responseFormat,
"voice" => $cloneAudioFullDataUri
]
];
五、项目文件结构
├─ config.php #配置文件，tp‑key、模型、音色常量
├─ api.php #后端核心接口 JSON(预置/音色设计)+FormData文件上传(音色克隆)
├─ index.php #主页面 FoxUI，多Tab，录音上传合成
├─ setup.php #设置页面，写入config.php保存token
└─ debug‑api‑response.php #API调试工具
六、总结收获
- 不要拿OpenAI TTS经验直接套MiMo，接口路径、入参、返回格式完全不一样。
- 音色克隆坑点最多：二进制传输方式、data‑URI前缀、音频格式、样本质量，每一项出错就会报
Param Incorrect。 - Web网页录音兼容性很受限，PC端可以实现完整录音转码，手机浏览器受底层API限制很难做到全兼容。
- Token‑Plan要遵守使用协议，仅限本地个人学习，禁止对外中转服务。
项目地址：https://gitee.com/xiaojievip/mimov25yuyin
📝 日常记录：这是一个基于小米MiMo Token‑Plan的PHP网页语音合成工具开发过程的完整记录，包含了所有踩过的坑和解决方案。
💡 适用人群：需要使用小米MiMo进行语音合成的PHP开发者
🔧 技术栈：PHP + FoxUI + lamejs + curl
