如何调用MiniMax开放平台API？从API Key到多模态实战
上周有个做智能客服的朋友来问我，国内哪家大模型的接口接起来最省事。我几乎没犹豫就说了 MiniMax。不是因为它参数最大，而是因为它的接口设计和文档排布，对一个下午就要出 Demo 的人来说，友好得有点反常。
这篇文章我把自己从申请 API Key 到跑通文本、语音、视频三类接口的全过程记录下来，中间踩的坑也一并写上，省得你再走一遍。
核心结论摘要：MiniMax开放平台API采用 Bearer Token + GroupId 双要素鉴权，提供 OpenAI 兼容的文本推理接口、T2A 语音合成接口和异步的视频生成接口。个人开发者注册后即可获得试用额度，文本接口通常 30 分钟内就能跑通第一个请求。
MiniMax开放平台API到底是什么？先弄清产品版图
简单说，MiniMax开放平台API 是 MiniMax（名之梦科技）对外提供的大模型能力调用入口。这家公司 2021 年底成立，创始人是前商汤副总裁闫俊杰，属于国内最早一批 all-in 多模态的团队。它的开放平台把文本、语音、视频、音乐四条能力线统一到一套鉴权和计费体系下，这是我觉得比其他家省心的地方——不用注册四个账号。
据 MiniMax 官方开放平台文档（platform.minimaxi.com/document，2025 年持续更新）说明，目前对外可调用的核心模型大致分这几类：
| 能力线 | 代表模型 | 关键特征 | 调用形态 | |---|---|---|---| | 文本推理 | MiniMax-M1、MiniMax-Text-01、abab6.5 系列 | M1 为开源混合 MoE，激活参数 45.9B，支持 1M 长上下文 | 同步 / 流式 | | 视觉理解 | MiniMax-VL-01 | 图文混合输入 | 同步 | | 语音合成 | speech-02 系列 | 多语言、音色克隆 | 同步 | | 视频生成 | MiniMax-Hailuo-02 / video-01 | 文生视频、图生视频 | 异步轮询 | | 音乐生成 | music-01 | 人声+伴奏一体化生成 | 异步轮询 |
从 abab 到 M1：模型迭代的节奏
如果你去年接过 abab6.5，现在回头看会发现接口层面几乎没变，但底层换了一轮。2025 年 1 月开源 MiniMax-Text-01 和 VL-01，同年 6 月放出 MiniMax-M1，采用了混合 MoE 加 Lightning Attention 的架构，并用一种叫 CISPO 的强化学习算法做后训练（这部分细节写在了 MiniMax 的 GitHub 技术报告里，仓库名 MiniMax-AI/MiniMax-M1）。有意思的是，M1 把长上下文做到了 1M token 级别，而推理成本压得相当低——我实测跑了一篇 8 万字的技术文档摘要，账单不到一杯咖啡钱。
计费逻辑：按 token 还是按次？
文本类按输入/输出 token 分别计价，语音按字符数，视频按生成时长和分辨率档位。坦白讲，视频这块的价格波动最让人摸不准，因为它跟当前排队负载有关。具体单价请以官方定价页为准，我下面只谈实测体感。
API Key 申请与鉴权机制拆解
这一节是很多人第一次卡住的地方。MiniMax 的鉴权不是单一的 API Key，而是 Key + GroupId 的组合，这点跟 OpenAI 不一样。
三步拿到你的 API Key
- 用手机号或邮箱注册开放平台账号，完成实名认证（个人认证即可拿到试用额度）。
- 进入「账户管理 - 接口密钥」，点「创建新的密钥」。**密钥只在创建时完整展示一次，务必当场复制保存**，页面刷新后就只剩掩码了。
- 在「账户管理 - 基本信息」里找到 GroupId，它是一串数字，调用时作为 URL 参数或请求体字段传入。
我见过至少三个同事栽在第二步：创建完密钥没复制，回头只能删掉重建。这不是 MiniMax 独有的设计，但确实容易忽略。
鉴权头怎么写
所有请求统一使用 Bearer 鉴权：
Authorization: Bearer Content-Type: application/json
GroupId 则通常拼在 URL 上，比如 `?GroupId=1234567890`。忘了带它，接口会返回一个语焉不详的参数错误，排查起来挺费劲。
好消息：它兼容 OpenAI SDK
这是我最欣赏的一点。MiniMax 提供了 OpenAI 兼容的文本接口，意味着你现有的 LangChain、LlamaIndex 代码基本只需要改 `base_url` 和 `api_key` 两个字段。下面这段是我实际项目里跑的：
文本对话：直接复用 openai SDK，迁移成本几乎为零
from openai import OpenAI
client = OpenAI( api_key="你的MiniMax API Key", # 平台「接口密钥」页面创建 base_url="https://api.minimaxi.com/v1", # 注意结尾不要多带斜杠 )
resp = client.chat.completions.create( model="MiniMax-M1", # 也可换成 abab6.5s 等 messages=[ {"role": "system", "content": "你是一名简洁的技术助理"}, {"role": "user", "content": "用一句话解释什么是混合专家架构"}, ], temperature=0.3, stream=False, ) print(resp.choices[0].message.content)
如果 SDK 路由不通（版本差异导致），可以直接用 requests 打到 `/v1/text/chatcompletion_v2`，效果一样。
多模态接口实战：语音与视频怎么调
文本接口跑通只是开胃菜。真正让我觉得这套 API 有差异化价值的，是语音和视频这两块。
语音合成：返回的是十六进制，别踩这个坑
第一次调 T2A 接口时我盯着返回结果愣了半天——`data.audio` 字段是一长串十六进制字符串，不是二进制。直接写文件会得到一个乱码文件。正确姿势是转回 bytes：
import requests
url = "https://api.minimaxi.com/v1/t2a_v2?GroupId=你的GroupId" headers = { "Authorization": "Bearer 你的API Key", "Content-Type": "application/json", } payload = { "model": "speech-02-hd", "text": "欢迎使用 MiniMax 开放平台 API 的语音合成能力。", "stream": False, # 长文本可开启流式降低首包延迟 "voice_setting": { "voice_id": "male-qn-qingse", # 音色ID，平台有音色列表可查 "speed": 1.0, "vol": 1.0, "pitch": 0, }, "audio_setting": {"format": "mp3", "sample_rate": 32000, "bitrate": 128000}, } r = requests.post(url, headers=headers, json=payload, timeout=60) data = r.json()
关键一步：hex 转二进制再落盘
audio_hex = data["data"]["audio"] with open("output.mp3", "wb") as f: f.write(bytes.fromhex(audio_hex)) print("合成完成，文件大小:", len(audio_hex) // 2, "字节")
顺带提一句，语音接口有单次文本长度上限，长文章必须自己切片再拼接。我第一次做有声书项目时没注意，直接把 3000 字甩进去，接口报了错。
视频生成：异步轮询的节奏感
视频是异步任务，逻辑是「提交 → 拿 task_id → 轮询状态 → 换下载地址」。轮询间隔官方建议 10 秒左右，我一开始设成 1 秒，结果把自己的请求配额烧了一大截，还没拿到更快的结果。
import time, requests
H = {"Authorization": "Bearer 你的API Key", "Content-Type": "application/json"} GID = "你的GroupId"
第一步：提交生成任务
create = requests.post( f"https://api.minimaxi.com/v1/video_generation?GroupId={GID}", headers=H, json={"model": "MiniMax-Hailuo-02", "prompt": "一只橘猫在雨天的窗台上打哈欠，电影感侧逆光"}, ) task_id = create.json()["task_id"]
第二步：轮询，直到状态变成 Success
while True: q = requests.get( f"https://api.minimaxi.com/v1/query/video_generation?task_id={task_id}&GroupId={GID}", headers=H, ).json() if q.get("status") == "Success": print("file_id:", q["file_id"]) # 再用 /v1/files/retrieve 换真实下载链接 break time.sleep(10)
踩坑记录与性能体感
说几个文档里不太会写、但实际会遇到的点。
延迟方面，文本流式接口的首字延迟在工作日下午实测通常在一秒出头，比同量级的海外模型回国内节点要快，这大概是本地化的直接好处。语音合成一段 200 字的中文，端到端大概两三秒。视频就完全看运气了，快的两三分钟，慢的时候我排过十几分钟。
配额方面，免费试用额度够做 PoC，但要上生产必须提前充值。我建议在代码里把 4xx 和 5xx 分开处理——限流错误（通常是 1002 之类的业务码）应该走指数退避重试，而参数错误重试多少次都没用。
多模态大模型的组合玩法才是这套 API 真正有意思的地方。我做了一个小工具：用 M1 把长文章改写成口播稿，再丢给 T2A 生成音频，最后用视频接口配画面。三个接口串起来不到 200 行代码，出来的东西已经能直接发短视频平台了。这种「一站式」的体验，目前国内能完整提供的平台并不多。
学习路径与落地建议
如果你准备正式接入，我的建议是这个顺序：
- **第一周**：只跑文本接口，把鉴权、超时、重试、错误码这几件事做扎实。这层地基打不好，后面越接越乱。
- **第二周**：接入一个多模态能力，优先选语音。理由很简单，语音的调试反馈最直观，出问题了耳朵一听就知道。
- **之后**：再考虑视频这类异步、高成本的任务，并且一定要加任务落库，避免服务重启后 task_id 丢失。
选型上，我想说句实在话：MiniMax 不是所有场景的最优解。如果只是做简单的分类、抽取任务，用更小的模型更划算；但如果你的产品需要文本 + 语音 + 视频一条链路打通，那它的综合成本优势会非常明显。工具选型从来不是选最强的，是选最合手的。
关键要点速览
- MiniMax开放平台API 的鉴权是 **API Key + GroupId** 双要素，缺一不可，密钥只在创建时展示一次。
- 文本接口**兼容 OpenAI SDK**，迁移成本极低，改 `base_url` 和 `api_key` 即可。
- 语音合成返回的是 **hex 编码音频**，必须 `bytes.fromhex()` 转二进制再落盘。
- 视频生成是**异步任务**，轮询间隔建议 10 秒，并做好 task_id 持久化。
- MiniMax-M1 支持 1M 上下文，长文档处理场景下性价比突出。
相关推荐
阅读相关专题 想系统对比国内几家大模型的接口差异和定价策略，可以看我们在 VergeX 国产大模型专题 里维护的长期更新清单。
查看工具推荐 如果你还在纠结用哪家的 API 起步，VergeX AI 工具导航 按能力维度整理了主流平台的接入成本和适用场景，省去逐个试错的时间。
订阅更新 我们会持续跟踪 MiniMax 及其他平台的接口变更、新模型发布和定价调整。想要第一时间收到推送，可以订阅 VergeX 的邮件通讯，或在导航站底部扫码加入微信读者群。
延伸阅读
- [多模态大模型调用成本对比](https://nav.vergex.cn)
- [大模型推理服务的超时与重试设计](https://nav.vergex.cn)