meijiaka-zy/docs/minimax-api-dev.md

MiniMax API 开发文档

文档来源：https://platform.minimaxi.com / https://platform.minimax.io 整理时间：2026-04-21

---

1. 服务地址

区域	Base URL
中国大陆	https://api.minimaxi.com
国际	https://api.minimax.io

2. 认证方式

Bearer Token

Authorization: Bearer {API_KEY}

• 在 MiniMax 平台 账户管理 > 接口密钥 中创建
• Key 前缀通常为 sk-api- 或 sk-cp-

3. 通用响应格式

{
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

• status_code = 0 表示成功
• 非零表示错误，具体含义见各接口错误码说明

---

4. 文本生成（Chat Completion）

4.1 接入方式

支持三种 SDK/协议接入：

1. HTTP 直连 — 原生 REST API
2. OpenAI SDK — 兼容 /chat/completions 接口
3. Anthropic SDK — 兼容 Claude 风格接口

4.2 模型列表

模型名称	上下文窗口	说明
MiniMax-M2.7	204,800	旗舰模型，自迭代能力，约 60 tps
MiniMax-M2.7-highspeed	204,800	M2.7 高速版，约 100 tps
MiniMax-M2.5	204,800	性能与性价比平衡，约 60 tps
MiniMax-M2.5-highspeed	204,800	M2.5 高速版，约 100 tps
MiniMax-M2.1	204,800	多语言编程增强
MiniMax-M2	204,800	Agentic 能力、高级推理

4.3 HTTP 接口

POST /v1/text/chatcompletion_v2
Content-Type: application/json
Authorization: Bearer {API_KEY}

请求体示例：

{
  "model": "MiniMax-M2.7",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "max_tokens": 1024,
  "temperature": 0.7,
  "stream": false
}

响应示例：

{
  "id": "04ecb5d9b1921ae0fb0e8da9017a5474",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Hello! How can I assist you?",
        "role": "assistant",
        "name": "MiniMax AI",
        "reasoning_content": "..."
      }
    }
  ],
  "created": 1755153113,
  "model": "MiniMax-M2.7",
  "usage": {
    "total_tokens": 249,
    "prompt_tokens": 26,
    "completion_tokens": 223,
    "completion_tokens_details": {
      "reasoning_tokens": 214
    }
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": ""
  }
}

4.4 关键字段说明

字段	类型	说明
model	string	模型名称
messages	array	对话消息列表，支持 system/user/assistant
max_tokens	int	最大输出 token 数
temperature	float	采样温度，0-1
stream	bool	是否流式输出
reasoning_content	string	推理过程内容（M2.7 等模型支持）

---

5. 语音合成（TTS）

5.1 能力概述

• 同步 TTS：单次最多 10,000 字符，推荐 ≤3000 字符用非流式，>3000 用流式
• 异步长文本 TTS：单次最多 100 万字符，适合书籍/长文本
• 支持 300+ 系统音色 + 自定义克隆音色
• 支持 40 种语言
• 可调节音量、音调、语速、输出格式

5.2 模型列表

模型	说明
speech-2.8-hd	最新 HD 模型，语气词渲染，音色相似度极高
speech-2.8-turbo	最新 Turbo 模型，速度优先
speech-2.6-hd	HD 模型，韵律优秀，克隆相似度高
speech-2.6-turbo	Turbo 模型，支持 40 语言
speech-02-hd	韵律稳定，复刻相似度和音质突出
speech-02-turbo	小语种增强，性能出色
speech-01-hd	早期 HD 模型
speech-01-turbo	早期 Turbo 模型

5.3 同步 TTS HTTP 接口

POST /v1/t2a_v2
Content-Type: application/json
Authorization: Bearer {API_KEY}

备用地址： https://api-bj.minimaxi.com/v1/t2a_v2

请求体：

{
  "model": "speech-2.8-hd",
  "text": "你好，这是测试文本。<#1.5#>这是停顿后的内容。",
  "voice_id": "male-qn-qingse",
  "speed": 1.0,
  "vol": 1.0,
  "pitch": 0,
  "audio_sample_rate": 32000,
  "bitrate": 128000,
  "format": "mp3",
  "language_boost": "auto",
  "subtitle_enable": false,
  "output_format": "url"
}

关键字段说明：

字段	类型	说明
model	string	TTS 模型版本
text	string	待合成文本，≤10000 字符。支持 <#x#> 停顿标记（x 单位秒，0.01-99.99）和 (laughs) 等语气词标签（仅 2.8 模型）
voice_id	string	音色 ID。系统预设音色或克隆/设计音色
speed	float	语速，默认 1.0
vol	float	音量，默认 1.0
pitch	int	音调，默认 0
format	string	音频格式：mp3/pcm/flac/wav（wav 仅非流式）
audio_sample_rate	int	采样率：16000/24000/32000/44100/48000
bitrate	int	比特率：16000/32000/64000/128000
language_boost	string	小语种增强：auto 或具体语言名
subtitle_enable	bool	是否生成字幕（句子级时间戳）
output_format	string	输出形式：url（有效期 24h）或 hex
stream	bool	是否流式输出

5.4 异步长文本 TTS

创建任务：

POST /v1/t2a_async_create

查询任务：

GET /v1/t2a_async_query?task_id={task_id}

• 单次最多 100 万字符
• 支持通过 file_id 上传文本文件作为输入
• 返回音频 URL 有效期 9 小时
• 支持句子级时间戳（字幕）

---

6. 语音克隆（Voice Cloning）

6.1 快速复刻

从用户上传的音频文件快速克隆音色。

POST /v1/voice_clone
Content-Type: application/json
Authorization: Bearer {API_KEY}

请求体：

{
  "model": "speech-2.8-hd",
  "voice_name": "我的音色",
  "audio_url": "https://example.com/voice_sample.mp3",
  "sample_audio_url": "https://example.com/enhance_sample.mp3"
}

说明：

• 支持单声道/立体声音频
• audio_url：目标克隆音频（5-30秒，人声干净）
• sample_audio_url：可选，示例音频提升克隆质量
• 克隆本身不收费，首次使用克隆音色进行 TTS 合成时收费
• 克隆音色为临时音色，需在 7 天内（168 小时）至少使用一次 TTS 合成，否则会被清除

6.2 查询克隆任务

GET /v1/voice_clone?task_id={task_id}

任务完成后返回 voice_id，可直接用于 TTS 接口。

6.3 音色设计（Voice Design）

根据文字描述生成自定义音色。

POST /v1/voice_design

说明：

• 推荐模型：speech-02-hd
• 生成的 voice_id 同样可用于 TTS
• 也是临时音色，7 天内需使用一次

---

7. 视频生成

7.1 能力概述

• 文生视频、图生视频、首尾帧视频、主体参考视频
• 支持镜头控制（15 种运镜指令）
• 异步任务模式：创建 → 查询 → 下载

7.2 模型列表

模型	说明
MiniMax-Hailuo-2.3	最新视频模型，肢体动作、面部表情、物理表现突破
MiniMax-Hailuo-2.3-Fast	图生视频高速版，性价比更高
MiniMax-Hailuo-02	1080P 原生，SOTA 指令遵循，极致物理表现
T2V-01-Director	导演模式，支持运镜指令
T2V-01	标准文生视频

7.3 文生视频

POST /v1/video_generation
Content-Type: application/json
Authorization: Bearer {API_KEY}

请求体：

{
  "model": "MiniMax-Hailuo-2.3",
  "prompt": "A cat wearing sunglasses, sitting on a beach chair. [Push in] The camera slowly zooms in on the cat's face.",
  "prompt_optimizer": true,
  "duration": 6,
  "resolution": "768P",
  "callback_url": "https://your-domain.com/callback"
}

关键字段：

字段	类型	说明
model	string	视频模型
prompt	string	视频描述，≤2000 字符。支持 [命令] 运镜语法
prompt_optimizer	bool	是否自动优化 prompt，默认 true
duration	int	时长（秒）：6 或 10，默认 6
resolution	string	分辨率：720P/768P/1080P
callback_url	string	回调地址（可选）

运镜指令（15 种）：

类型	指令
平移	[Truck left], [Truck right]
摇镜	[Pan left], [Pan right]
推/拉	[Push in], [Pull out]
升降	[Pedestal up], [Pedestal down]
俯仰	[Tilt up], [Tilt down]
变焦	[Zoom in], [Zoom out]
晃动	[Shake]
跟踪	[Tracking shot]
固定	[Static shot]

• 组合运镜：[Pan left,Pedestal up]（最多 3 个同时）
• 顺序运镜：按文本顺序出现

7.4 查询视频任务

GET /v1/video_generation?task_id={task_id}

状态：processing → success/failed

成功时返回 file_id，用文件管理 API 下载。

7.5 图生视频 / 首尾帧视频 / 主体参考视频

• 图生视频：提供首帧图片 URL
• 首尾帧视频：提供首帧 + 尾帧图片 URL
• 主体参考视频：提供参考图片，保持主体一致性

具体字段与文生视频类似，额外增加图片 URL 参数。

7.6 Video Agent（模板视频）

基于预设模板快速生成视频。

模板 ID	模板名称	说明
392747428568649728	Diving	上传照片生成跳水视频
393769180141805569	Run for Life	宠物照片 + 野兽类型，生成野外求生视频
397087679467597833	Transformers	汽车照片生成变形机甲视频
393881433990066176	Still rings routine	上传照片生成吊环体操视频
393498001241890824	Weightlifting	宠物照片生成举重视频
393488336655310850	Climbing	上传照片生成攀岩视频

---

8. 图片生成

POST /v1/image_generation
Content-Type: application/json
Authorization: Bearer {API_KEY}

模型： image-01 / image-01-live（手绘/卡通风格增强）

能力：

• 文生图
• 图生图（以人物为主体的图像参考）
• 支持自定义宽高比和分辨率

---

9. 音乐生成

POST /v1/music_generation
Content-Type: application/json
Authorization: Bearer {API_KEY}

模型： music-2.6

能力：

• 根据音乐描述（prompt）和歌词生成歌曲
• 支持翻唱（基于参考音频一键生成翻唱版本）
• 支持风格迁移和自动歌词提取

---

10. 文件管理

用于配合视频/音频生成任务上传和下载文件。

操作	方法	路径
上传文件	POST	/v1/files/upload
文件列表	GET	/v1/files
获取文件信息	GET	/v1/files/{file_id}
下载文件内容	GET	/v1/files/{file_id}/content
删除文件	DELETE	/v1/files/{file_id}

支持格式：

类型	格式
文档	pdf, docx, txt, jsonl
音频	mp3, m4a, wav

容量限制：

• 总容量：100GB
• 单个文件：512MB

---

11. 回调机制（Callback）

视频生成等异步任务支持 Webhook 回调。

配置方式

在创建任务时传入 callback_url。

验证流程

1. MiniMax 首次向回调地址发送验证请求，body 中包含 challenge 字段
2. 你的服务器需在 3 秒内原样返回 {"challenge": "..."}
3. 验证通过后，后续任务状态变更会自动推送

推送格式

{
  "task_id": "115334141465231360",
  "status": "success",
  "file_id": "205258526306433",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

---

12. 定价参考

服务	计费方式	参考价格
文本生成 (M2)	按 Token	$0.3/1M input, $1.2/1M output
文本生成 (M2.5/2.7 highspeed)	按 Token	$0.6/1M input, $2/1M output
TTS (Turbo)	按字符	$60/1M 字符
TTS (HD)	按字符	$100/1M 字符
视频生成 (Hailuo 6s 768P)	按任务	~$0.33/条
图片生成	按张	~$0.0035/张

---

13. 错误码速查

status_code	说明
0	成功
1000	参数错误
1001	鉴权失败
1002	余额不足
1003	请求频率限制
1004	服务内部错误
1005	任务不存在
1006	任务处理中
1007	任务失败
1008	文件不存在
1009	文件格式不支持
1010	文本过长
1011	非法字符过多（TTS 异步）

---

14. 接入建议

14.1 TTS 接入

import httpx

async def minimax_tts(text: str, voice_id: str, api_key: str) -> str:
    """同步 TTS，返回音频 URL"""
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.minimax.io/v1/t2a_v2",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "model": "speech-2.8-hd",
                "text": text,
                "voice_id": voice_id,
                "speed": 1.0,
                "output_format": "url",
                "format": "mp3",
            },
            timeout=60,
        )
        data = resp.json()
        if data.get("base_resp", {}).get("status_code") != 0:
            raise Exception(data["base_resp"]["status_msg"])
        return data["data"]["audio_url"]

14.2 视频生成接入

import httpx
import asyncio

async def create_video(prompt: str, api_key: str) -> str:
    """创建视频任务，返回 task_id"""
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            "https://api.minimax.io/v1/video_generation",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "model": "MiniMax-Hailuo-2.3",
                "prompt": prompt,
                "duration": 6,
                "resolution": "768P",
            },
        )
        data = resp.json()
        return data["data"]["task_id"]

async def poll_video(task_id: str, api_key: str) -> str:
    """轮询视频任务，返回 file_id"""
    async with httpx.AsyncClient() as client:
        for _ in range(60):  # 最多等 10 分钟
            resp = await client.get(
                f"https://api.minimax.io/v1/video_generation?task_id={task_id}",
                headers={"Authorization": f"Bearer {api_key}"},
            )
            data = resp.json()
            status = data["data"].get("status")
            if status == "success":
                return data["data"]["file_id"]
            if status == "failed":
                raise Exception("视频生成失败")
            await asyncio.sleep(10)
        raise TimeoutError("视频生成超时")

14.3 语音克隆 + TTS 完整流程

async def clone_and_synthesize(audio_url: str, text: str, api_key: str):
    """克隆音色并合成语音"""
    async with httpx.AsyncClient() as client:
        # 1. 提交克隆
        resp = await client.post(
            "https://api.minimax.io/v1/voice_clone",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "model": "speech-2.8-hd",
                "voice_name": "克隆音色",
                "audio_url": audio_url,
            },
        )
        task_id = resp.json()["data"]["task_id"]

        # 2. 轮询克隆结果
        voice_id = None
        for _ in range(120):
            resp = await client.get(
                f"https://api.minimax.io/v1/voice_clone?task_id={task_id}",
                headers={"Authorization": f"Bearer {api_key}"},
            )
            data = resp.json()["data"]
            if data.get("status") == "succeed":
                voice_id = data["voice_id"]
                break
            await asyncio.sleep(5)

        if not voice_id:
            raise Exception("克隆失败或超时")

        # 3. 用克隆音色合成 TTS
        resp = await client.post(
            "https://api.minimax.io/v1/t2a_v2",
            headers={"Authorization": f"Bearer {api_key}"},
            json={
                "model": "speech-2.8-hd",
                "text": text,
                "voice_id": voice_id,
                "output_format": "url",
            },
        )
        return resp.json()["data"]["audio_url"]

---

15. 注意事项

1. 临时音色有效期：克隆音色和设计的音色均为临时音色，需在 7 天内至少使用一次 TTS 合成，否则会被清除。
2. TTS URL 有效期：同步 TTS 返回的音频 URL 有效期 24 小时，异步长文本 TTS 的 URL 有效期 9 小时。
3. 流式输出：同步 TTS 支持流式返回（stream: true），适合实时语音场景。
4. 语言增强：language_boost 设为 auto 可让模型自动判断语言，提升小语种和方言效果。
5. 视频分辨率与时长：不同模型支持的分辨率和时长组合不同，详见第 7 节表格。
6. 文本停顿标记：TTS 文本中可用 <#1.5#> 控制停顿，用 (laughs) 等插入语气词（仅 2.8 模型）。