夜雨聆风接入 MiniMax Token Plan 3天，一直在调试，踩过的坑比你想象的多。
这篇文章是实打实的血泪总结，14 个坑，每一个都有真实报错证据。不是什么"建议""注意事项"，是踩下去才知道疼的硬核教训。
如果你正在接 MiniMax API，或者接了还没踩够，这篇收藏起来。
前两天我成为了MiniMax Token Plan的Max年度套餐，冲着他们家的套餐里面有图片，有音频，有视频，才选了这个套餐，然后，使用心得在文末，想来大家感受应该是差不多的吧。
第一节：14个坑
大坑-01：OpenClaw 接入 minimax-m2.7，默认没有图像识别能力
minimax-m2.7 是对话模型，OpenClaw 接入后默认不能理解图片，官方文档只给了一点OAuth登录的解释会自动配置，
但我的OpenClaw是纯手动配置的，不知道啥是OAuth，啥是minima-portal啊，我在飞书客服群里面看大家的提问，10个里面至少有2个在问，为啥不能图像识别的，然后我只能在网上各种找方案，一个一个试，最后才发现 m2.7 不支持图片理解，必须换MiniMax-VL-01，并需要手动在 openclaw.json 里的tools下面配置：
"media": {"image": {"enabled": true,"models": [{"type": "provider","provider": "minimax","model": "MiniMax-VL-01","capabilities": ["image"]}]}}
表现：上传图片给 m2.7 模型，它回复"无法处理图片"或直接忽略图片内容。配了MiniMax-VL-01 之后，才能正确识别。【NEURALOFT实录，2026-03-26】
大坑-02：TokenPlan 文档不列可用模型，开发者只能盲试
TokenPlan 音频额度的官方文档标题是"Text to Speech HD"，但实际这个不是模型名......
开发者只能从 turbo 试到 hd，从 2.8 试到 2.6，一个一个试过去才知道哪个能跑。文档只告诉你"建议什么"，不告诉你"你能用什么"。同样的问题在视频额度也是。【Chief Marshal实测，2026-03-29】
中坑-03：音频和视频接口，请求发送即扣额度，失败也不例外
这个坑踩的的确不是很爽，Plan里面每日的额度也没多少，调试音乐生成技能时，因为参考代码执行不规范，消耗了大量无效额度——接口请求发出去就算一次调用，无论返回成功还是失败。
{"base_resp": {"status_code": 2013, "status_msg": "invalid params..."}}
哪怕你的请求因为参数错误被拒绝，这一次调用依然计入额度。文档没有写"失败也计入额度"，开发者以为调试时不成功就不扣，这是最冤的一笔账。
Pixie 在 2026-03-29 制作 minimax-music 技能时，擅自尝试 instrumental 模式，消耗了大量无效额度。规范做法：消耗额度的操作（API 调用）要先评估必要性，不确定就先问。【Pixie实录，2026-03-29】
小坑-04：Prompt 超 1500 字符，接口直接拒绝
图生图场景下，prompt 写得太详细反而害死你。
实测超过 1500 字符，接口直接拒绝出图，错误码模糊，连"超限"两个字都不给你明说。只能逐字删减，二次尝试，才发现是字符数卡住了。
{"base_resp": {"status_code": 4xx, "status_msg": "invalid request"}}
解决方案：精简到 1200 字符以内才能稳定出图。【Pixie实录，2026-03-25】
小坑-05：图生图返回 HTTP 200，但 data 是 null
i2i（图生图）模式有个玄学问题：请求发出去了，接口返回 200，但 data 字段是空的。
{"status_code": 0, "data": null, "status_msg": "success"}
HTTP 200 不等于业务成功。这不是你的 prompt 问题，可能是接口偶发性异常。真相是：重发一次请求就出了。【Pixie实录，2026-03-25】
小坑-06：aspect_ratio 和 width/height 同时传，尺寸被静默覆盖
有的开发者想着"我指定了比例再指定个具体尺寸，双保险"。
实测结果：同时传 aspect_ratio 与 width/height，接口优先用 aspect_ratio，你的 width/height 被静默忽略。出来的图尺寸完全对不上预期。
MiniMax skill 文档明确写明：同时传这两组参数，实际行为以 aspect_ratio 为准。【Pixie实录，skill文档交叉验证，2026-03-25】
小坑-07：minimax-m2.7 是对话模型，不是图像模型
这是最容易踩的模型 ID 混淆陷阱。
openclaw.json 里配置的 minimax-m2.7 是用来对话聊天的，图像生成接口用的是 image-01。用对话模型 ID 去调图像接口，你会得到一个含义不明的报错，而不是一句"请换用 image-01"。
文档里有 image-01，但没有明确标注"这是图像专用 ID"，开发者顺手复制粘贴，一调就挂。【Pixie实录，skill文档明确说明，2026-03-25】
小坑-08：视频查询接口 URL 没注意是不一样的
调视频生成最常犯的错：以为"查询就是提交接口加个 task_id 参数"。
实测结果：提交是 POST /v1/video_generation，查询是 GET /v1/query/video_generation——路径不一样。
{"base_resp": {"status_code": 404, "status_msg": "path /v1/video_generation does not exist"}}
接口不会报"路径不存在"，它只是不返回你数据，让你以为是任务还在排队。查了半天才发现 URL 写错了。【Pixie实录，2026-03-26】
小坑-09：以为 ff2v / s2v 是 t2v / i2v 的别名
ff2v（首尾帧混合）和 s2v（主体参考）被一些开发者当成"同一种功能的另一种写法"。
实测结论：它们是完全独立的模型，和 t2v（文生视频）、i2v（图生视频）并列，不是别名关系。调用时模型参数填错了，接口不会自动映射到正确模型。【Pixie实录，2026-03-26】
小坑-10：fl2v / s2v 超出 plan 权限，白跑一趟
fl2v（首尾帧混合）和 s2v（主体参考）听着很美，跑起来才发现：当前 plan 无权限，接口直接返回不支持。
{"base_resp": {"status_code": 2056, "status_msg": "usage limit exceeded"}}
你以为是参数问题，重试一百遍还是同样报错。真相是账号等级限制，不是你的请求问题。【Pixie实录，2026-03-26】
小坑-11：TokenPlan Key 不支持 speech-2.8-turbo
用 TokenPlan 类型 Key 跑 TTS，照着文档写 speech-2.8-turbo，接口返回：
{"base_resp":{"status_code":2061,"status_msg":"your current token plan not support model, speech-2.8-turbo"}}请求参数完全正确，模型名称也没写错，但 TokenPlan 就是不让你用。排查一圈才发现：TokenPlan Key 只支持 speech-2.8-hd，turbo 模型不在白名单里。这不是代码问题，是 Key 类型和模型名的匹配问题。【Chief Marshal实测，2026-03-29】
小坑-12：同一个平台，多套 Key规则分散
如果你同时用 MiniMax 对话和图像能力，你会发现：
- 对话模型用
minimax-m2.7 - 图像模型用
image-01 - TTS 用
speech-2.8-hd
三套命名逻辑，臣妾记不住啊......TokenPlan Key 和普通 Key 能跑的模型还不一样，文档不写清楚，开发者不踩坑永远不知道。
这不是能力问题，这是文档和产品体验的问题。【NEURALOFT团队综合实测】
小坑-13：图片生成接口尺寸参数有上限
图片生成接口对尺寸有限制，不是你想生成多大就多大。
超过上限会直接报错，或者返回一张黑图。文档里写了取值范围，但没写清楚"最大值"到底是多少。上线用户一用就崩，但你不知道是尺寸超了。
实测结论：生成 1024 以上分辨率图片时，建议提前测好上限，并做好兜底处理。【Pixie实录，2026-03-25】
坑14：OpenClaw skill 脚本模型名与 TokenPlan 不匹配
我自己写的OpenClaw 的 minimax-tts skill，默认使用了 speech-2.8-turbo 模型，但 TokenPlan 实际只支持 speech-2.8-hd。这导致通过 OpenClaw 调用 TTS 时，默认参数直接报错。
排查过程：先以为是 API Key 配置问题，再以为是接口端点问题，最后实测多个模型才发现 TokenPlan 的 speech-2.8-hd 才是正确模型。这又一次印证了 TokenPlan 模型列表不透明的问题——调试好痛苦。
建议：使用 TokenPlan Key 时，所有 skill 的默认模型参数都需要对照实测结果修正，不能直接用文档默认值。【Chief Marshal实测，2026-03-29】
第二节：OpenClaw 的解法
踩完这些坑，我们把这些经验固化成了 OpenClaw skill 脚本，核心价值是四个：
1. 错误信息本地化
把接口返回的错误码（如 2061、2056、4xx）映射成可读的人类语言，新人拿到报错不再需要翻遍全网找答案。
2. 参数校验前置
在请求发出前就检查 prompt 长度、aspect_ratio 和 width/height 不同时传、模型 ID 正确性，把"接口报错"变成"本地拦截"。
3. 视频轮询封装
视频生成任务提交后封装了自动轮询逻辑，自动用正确的 GET /v1/query/video_generation 查询，不再靠人工记 URL。
4. 错误经验写成血泪教训，记录到团队memory中
所有错误经验统一写入团队血泪教训的memory中，以后再犯就喷。
第三节：实战案例：一条视频的生产全流程
背景： 本文需要一条 6 秒的片头展示视频（TokenPlan Hailuo-2.3-Fast 每日限额 2 次，每次最长 6 秒），配语音解说，用于社群传播。于是我在Discord群里面给大家布置任务，大家开始讨论，发散后收束开始任务，
步骤 1 — Lois 写文案，Chief 转 TTS
Chief Marshal 向 Lois 派单："出一版适合 TTS 朗读的口播文案，6 秒左右。" Lois 完成文案后，Chief Marshal 用 speech-2.8-hd 模型（注意，不是文档里默认的 turbo）提交 TTS 请求，生成音频文件，上传群频道预览。
步骤 2 — 图生图（封面）
Chief Marshal 向 Pixie 派单出一张产品封面图，prompt 控制在 1200 字符以内。Pixie 提交，——出图，上传群频道预览。
步骤 3 — 图生视频
用 i2v 模型把封面图转视频，设置时长 6 秒（TokenPlan 上限）。提交后用封装好的轮询脚本自动查询，几分钟后视频就绪。
步骤 4 — 视频压缩
视频原始体积偏大，用 ffmpeg H.264 crf23 压缩（360p 默认约 250KB，适合社群传播）。上传群频道预览。
步骤 5 — 音画合并（ffmpeg 实测可行）
用 ffmpeg 将 TTS 音频与视频合并：
NEURALOFT 已实测：Cut 5s 音频 + 6 秒视频 → 合并为完整 6s 音画文件，视频内容播放至音频结束。
步骤 6 — 发布
压缩后（0.7MB）分发到社群渠道。
整个链条：文案 → TTS → 图生图 → 图生视频 → 压缩 → 音画合并 → 发布，全程 OpenClaw skill 支撑。
附录：压缩方法速查
图片压缩
- 方法：ImageMagick（
magick命令） - 依赖：服务器需预装 ImageMagick（版本 7.1.1-26 Q16-HDRI）
- 要点：限制最大宽度 + 调整 JPEG 质量参数，输出到同目录
compressed/子目录
视频压缩
- 方法：ffmpeg H.264 crf23（标准）/ VP9 crf30（fallback）
- 依赖：服务器需预装 ffmpeg
- 要点：按分辨率分级（360p/480p/720p），自动降级适配，支持编码器自动检测（libopenh264 → h264_vaapi → h264_v4l2m2m → libx264）
音频
- 方法：MiniMax TTS API 内置参数（
--bitrate/--format） - 依赖：无额外工具，API 请求时直接指定
- 要点：可选 mp3/wav/pcm 格式，多档比特率（32k/64k/128k/256k），在 API 请求参数中指定，无需 ffmpeg 二次处理
最后一句：
MiniMax 的能力是真的强，订购这个套餐不亏，
对话：minimax-m2.7，5星好评，输出稳定，执行力够标准。
语音：speech-2.8-hd，4星好评，长文本生成中偶尔会飘，95%以上符合预期。
图像：image-01，
- 文生图，不评价大家都一样。
- 图生图，2星差不多够用，当抽盲盒了
视频：MiniMax-Hailuo-2.3，
- 文生视频，不评价大家都一样。
- 图生视频，4星优秀
- 首尾帧，不在套餐无法评测
- 主体，不在套餐无法评测
音乐：music-2.5，5星好评，大概我用的其他的比较少，感觉很给力
但TokenPlan 的方案也是真的让人想吐槽，看文档太累了...
踩完这 14 个坑，你的下一个任务会跑得比这轻松。
本文来自 NEURALOFT 团队实操记录，每一个坑都有原始记录可查，不捏造。
Pixie & Chief Marshal & 喵哥 联合出品
