MiniMax 语音合成技能#

功能概览#

功能API 端点说明异步语音合成/v1/t2a_async_v2长文本语音合成（推荐）查询任务状态/v1/query/t2a_async_query_v2查询异步任务进度音色快速复刻/v1/voice_clone克隆自定义音色查询可用音色/v1/get_voice获取音色列表删除音色/v1/del_voice删除自定义音色

重要说明#

同步端点 /v1/t2a_v1 已停用，返回 404。请使用异步端点 /v1/t2a_async_v2。

工作流程#

text

文本 → 创建任务 → 轮询状态 → 获取file_id → 下载音频 → 本地保存

快速开始#

异步语音合成#

python

import requests
import os

API_KEY = os.getenv("MINIMAX_API_KEY")

# 1. 创建任务
response = requests.post(
    "https://api.minimaxi.com/v1/t2a_async_v2",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "speech-2.8-hd",
        "text": "你好，欢迎使用 MiniMax 语音合成服务",
        "voice_setting": {
            "voice_id": "Chinese (Mandarin)_Lyrical_Voice",
            "speed": 1.0,
            "vol": 1.0,
            "pitch": 0,
            "emotion": "happy"
        },
        "audio_setting": {
            "audio_sample_rate": 32000,
            "format": "mp3",
            "bitrate": 128000,
            "channel": 1
        }
    }
)

task_id = response.json()["task_id"]

# 2. 查询状态
status_resp = requests.get(
    f"https://api.minimaxi.com/v1/query/t2a_async_query_v2?task_id={task_id}",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
status = status_resp.json()["status"]  # Processing / Success / Failed

# 3. 下载音频
if status == "Success":
    file_id = status_resp.json()["file_id"]
    file_resp = requests.get(
        f"https://api.minimaxi.com/v1/files/retrieve?file_id={file_id}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    download_url = file_resp.json()["file"]["download_url"]

    # 保存到本地
    save_dir = "~/.openclaw/workspace/assets/audios"
    os.makedirs(save_dir, exist_ok=True)
    save_path = os.path.join(save_dir, "output.mp3")

    audio_resp = requests.get(download_url)
    with open(save_path, 'wb') as f:
        f.write(audio_resp.content)

支持的模型#

模型说明适用场景speech-2.8-hd高清语音（推荐）高质量要求speech-2.8-turbo快速语音低延迟speech-2.6-hd高清语音标准质量speech-02-hd标准高清通用场景speech-01-hd基础高清简单场景

音色设置 (voice_setting)#

参数类型默认值说明voice_idstring必填音色 IDspeedfloat1.0语速 [0.5, 2]volfloat1.0音量 (0, 10]pitchint0语调 [-12, 12]emotionstring-情绪控制

情绪选项#

happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper

常用系统音色#

语言voice_id说明中文Chinese (Mandarin)_Lyrical_Voice抒情女声中文Chinese (Mandarin)_HK_Flight_Attendant空乘女声英文English_Graceful_Lady优雅女声英文English_Persuasive_Man说服力男声日文Japanese_Whisper_Belle日文低语

音频设置 (audio_setting)#

参数可选值默认值audio_sample_rate8000, 16000, 22050, 24000, 32000, 4410032000bitrate32000, 64000, 128000, 256000128000formatmp3, pcm, flacmp3channel1 (单声道), 2 (双声道)1

声音效果器 (voice_modify)#

参数类型说明pitchint音高调整 [-100, 100]intensityint强度调整 [-100, 100]timbreint音色调整 [-100, 100]sound_effectsstring音效

音效选项#

• spacious_echo - 空旷回音
• auditorium_echo - 礼堂广播
• lofi_telephone - 电话失真
• robotic - 电音

音色快速复刻#

1. 上传音频文件获取 file_id
2. 调用 /v1/voice_clone 进行复刻
3. 使用复刻的 voice_id 进行语音合成

输出目录#

生成的音频保存在： ~/.openclaw/workspace/assets/audios/

脚本工具#

• scripts/tts_sync.py - 异步语音合成（自动保存本地）
• scripts/tts_async.py - 异步语音合成 + 状态查询
• scripts/voice_clone.py - 音色复刻
• scripts/voice_list.py - 查询可用音色

命令行用法#

bash

# 语音合成
python tts_sync.py "要转换的文本" --voice "Chinese (Mandarin)_Lyrical_Voice"

# 查询音色列表
python voice_list.py --type all

# 音色复刻
python voice_clone.py --file-id 123456789 --voice-id "my_voice"

API 参考#

详细文档：

• references/tts-async.md - 异步语音合成
• references/voice-clone.md - 音色复刻
• references/voice-management.md - 音色管理