全文提要

小米MiMo-V2.5 Token-Plan PHP网页语音合成工具踩坑实录项目简介：基于小米MiMo Token-Plan，使用PHP + FoxUI实现本地网页调试工具，实现预置音色TTS、方言/唱歌标签、音色克隆、音色设计完整能力。 ⚠️重要协议提醒：Token-Plan仅限本地个人学习调试，禁止公网对外中转API服务，否则tp-开头的token会被...

内容由 AI 生成，仅供参考

小米MiMo-V2.5 Token-Plan PHP网页语音合成工具踩坑实录

项目简介：基于小米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,xxxx data-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调试工具