MiniMax Speech 音色管理
本文档介绍如何在 aijisu 中使用 MiniMax 音色能力,包括音色列表、声音克隆和声音设计。
如果你只是想把文字生成语音,请使用语音生成接口:
POST /v1/audio/tasksGET /v1/audio/tasks/{task_id}
如果你想创建自己的 voice_id,再把这个 voice_id 用到语音生成里,请使用本文档中的音色接口。
1. 支持能力
| 能力 | 接口 | 是否收费 | 说明 |
|---|---|---|---|
| 查询音色列表 | GET /v1/audio/voices | 否 | 返回系统公共音色和当前账号可见的私有音色 |
| 声音克隆 | POST /v1/audio/voices/clone | 是 | 通过参考音频生成一个可复用的 voice_id |
| 声音设计 | POST /v1/audio/voices/design | 是 | 通过文字描述设计一个可复用的 voice_id |
| 使用音色生成语音 | POST /v1/audio/tasks | 是 | 将 voice_id 传给 TTS 模型生成音频 |
当前推荐配合以下 TTS 模型使用:
| 模型名称 | 说明 |
|---|---|
minimax-speech-2.8-hd | 更新一代高清语音生成模型,适合自然口播、短视频、数字人、广告配音 |
minimax-speech-02-hd | 稳定高清语音生成模型,适合旁白、有声书、课程、客服、长文本播报 |
声音克隆和声音设计创建出来的 voice_id 可以在以上两个 TTS 模型中使用。
2. 接口地址
示例域名统一使用:
https:
实际调用时请替换为你的 aijisu API 域名。
| 操作 | 方法 | 路径 |
|---|---|---|
| 查询音色列表 | GET | /v1/audio/voices |
| 声音克隆 | POST | /v1/audio/voices/clone |
| 声音设计 | POST | /v1/audio/voices/design |
| 提交语音生成任务 | POST | /v1/audio/tasks |
| 查询语音生成任务 | GET | /v1/audio/tasks/{task_id} |
3. 鉴权方式
所有接口都使用 Bearer Token:
Authorization: Bearer YOUR_API_KEY
示例:
curl https://api.xxx.xx/v1/audio/voices \
-H "Authorization: Bearer YOUR_API_KEY"
4. 音色 ID 说明
voice_id 是调用 TTS 时使用的音色标识。
音色来源分为两类:
| 来源 | 说明 |
|---|---|
| 系统音色 | 平台内置公共音色,所有用户可查询和使用 |
| 私有音色 | 当前账号通过声音克隆或声音设计创建的音色,仅当前账号可见和可用 |
声音克隆和声音设计成功后,接口会返回一个 voice_id。你可以把它保存到自己的业务系统中,后续在 /v1/audio/tasks 中传入该 voice_id 来生成语音。
5. 查询音色列表
5.1 请求
GET /v1/audio/voices
可选查询参数:
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
model | string | 否 | 按兼容模型筛选音色,可选 minimax-speech-2.8-hd 或 minimax-speech-02-hd |
5.2 查询全部可见音色
curl "https://api.xxx.xx/v1/audio/voices" \
-H "Authorization: Bearer YOUR_API_KEY"
5.3 查询适用于 Speech 2.8 HD 的音色
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-2.8-hd" \
-H "Authorization: Bearer YOUR_API_KEY"
5.4 查询适用于 Speech 02 HD 的音色
curl "https://api.xxx.xx/v1/audio/voices?model=minimax-speech-02-hd" \
-H "Authorization: Bearer YOUR_API_KEY"
5.5 响应示例
{
"object": "audio.voice.list",
"model": "minimax-speech-2.8-hd",
"data": [
{
"voice_id": "Chinese (Mandarin)_Kind-hearted_Elder",
"display_name": "Kind-hearted Elder",
"language": "Chinese (Mandarin)",
"description": "MiniMax system voice",
"source_type": "system",
"visibility": "public",
"status": "active",
"compatible_models": [
"minimax-speech-2.8-hd",
"minimax-speech-02-hd"
],
"preview_audio_url": null,
"created_at": "2026-06-23T18:05:59Z"
},
{
"voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
"display_name": "local-design-taskid-smoke",
"language": "Chinese (Mandarin)",
"description": "Local smoke test for task id in sync response.",
"source_type": "voice_design",
"visibility": "private",
"status": "active",
"compatible_models": [
"minimax-speech-2.8-hd",
"minimax-speech-02-hd"
],
"preview_audio_url": "https://api.xxx.xx/media/preview.mp3",
"created_at": "2026-06-24T08:42:23Z"
}
]
}
5.6 响应字段
| 字段 | 说明 |
|---|---|
object | 固定为 audio.voice.list |
model | 当前筛选模型 |
data | 音色数组 |
data[].voice_id | 音色 ID,后续 TTS 调用传这个值 |
data[].display_name | 音色名称 |
data[].language | 音色语言 |
data[].description | 音色描述 |
data[].source_type | 音色来源,可能是 system、voice_clone、voice_design |
data[].visibility | 可见性,可能是 public 或 private |
data[].status | 状态,通常为 active |
data[].compatible_models | 可使用该音色的 TTS 模型 |
data[].preview_audio_url | 预览音频链接,可能为空 |
data[].created_at | 创建时间 |
6. 声音克隆
声音克隆用于从一段参考音频中提取声音特征,创建一个新的私有 voice_id。
适合场景:
- 克隆主播、讲师、客服、品牌代言人的声音
- 为数字人生成固定音色
- 为课程、有声书、短视频矩阵复用同一个声音
- 把线下录音中的声音整理成可重复调用的 TTS 音色
6.1 请求
POST /v1/audio/voices/clone
请求体为 JSON。
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
audio_url | string | 是 | 参考音频 URL,需要接口服务可访问 |
text | string | 建议 | 参考音频对应文本或预览文本,用于提升克隆质量和生成预览 |
preview_text | string | 否 | text 的兼容字段。若同时传,建议与 text 保持一致 |
display_name | string | 否 | 音色名称,便于列表展示 |
name | string | 否 | display_name 的兼容字段 |
language | string | 否 | 音色语言,例如 Chinese (Mandarin)、English |
description | string | 否 | 音色描述 |
noise_reduction | boolean | 否 | 是否启用降噪 |
need_volume_normalization | boolean | 否 | 是否进行音量归一化 |
accuracy | number/string | 否 | 克隆精度相关参数,按平台当前支持透传 |
6.2 参考音频建议
| 项目 | 建议 |
|---|---|
| 音频内容 | 单人说话,背景干净 |
| 音频时长 | 建议 10 秒以上,过短会影响相似度 |
| 录音质量 | 尽量无混响、无音乐、无明显噪声 |
| 说话方式 | 自然稳定,不要频繁变声或多人交替 |
| 文本匹配 | 如果知道音频原文,建议把原文放到 text |
| 授权合规 | 仅克隆你有权使用的声音 |
6.3 最小请求示例
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://example.com/audio/reference-speaker.mp3",
"text": "大家好,欢迎来到今天的课程。我们会用简单的方法讲清楚这个概念。",
"display_name": "course-teacher-voice",
"language": "Chinese (Mandarin)"
}'
6.4 带降噪和音量归一化
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://example.com/audio/noisy-reference.wav",
"text": "这是一个用于声音克隆的参考音频,请尽量保持音色自然稳定。",
"display_name": "cleaned-brand-speaker",
"language": "Chinese (Mandarin)",
"description": "品牌讲解类克隆音色",
"noise_reduction": true,
"need_volume_normalization": true
}'
6.5 英文主播声音克隆
curl -X POST "https://api.xxx.xx/v1/audio/voices/clone" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://example.com/audio/english-host.mp3",
"text": "Welcome back to the show. Today we are going to explore a simple but powerful idea.",
"display_name": "english-podcast-host",
"language": "English",
"description": "Warm English podcast host voice"
}'
6.6 响应示例
{
"object": "audio.voice",
"model": "minimax-voice-clone",
"task_id": "task_abc123",
"voice_id": "VoiceClone123456",
"preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
"voice": {
"voice_id": "VoiceClone123456",
"display_name": "course-teacher-voice",
"language": "Chinese (Mandarin)",
"description": "品牌讲解类克隆音色",
"source_type": "voice_clone",
"visibility": "private",
"status": "active",
"compatible_models": [
"minimax-speech-2.8-hd",
"minimax-speech-02-hd"
],
"preview_audio_url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
"created_at": "2026-06-24T08:42:23Z"
},
"billing_contract": {
"billing_version": "media-v1",
"public_model": "minimax-voice-clone",
"operation": "audio.voice_clone",
"settlement_policy": "fixed_at_estimate",
"billing_stage": "final",
"facts": {
"voice_clones": 1,
"preview_characters": 36
}
},
"outputs": [
{
"url": "https://api.xxx.xx/media/voice-clone-preview.mp3",
"type": "audio"
}
]
}
7. 声音设计
声音设计用于通过文字描述生成一个新的私有 voice_id,不需要上传参考音频。
适合场景:
- 为短视频账号设计固定口播音色
- 为数字人设计声音人设
- 为游戏角色、剧情角色、广播主持人设计声音
- 快速生成客服、课程、广告、旁白音色
- 没有参考音频,但有明确声音描述的场景
7.1 请求
POST /v1/audio/voices/design
请求体为 JSON。
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 声音设计描述,描述音色、性别、年龄感、语言、情绪、场景等 |
preview_text | string | 是 | 用于生成预览音频的文本 |
text | string | 否 | preview_text 的兼容字段 |
display_name | string | 否 | 音色名称,便于列表展示 |
name | string | 否 | display_name 的兼容字段 |
language | string | 否 | 音色语言,例如 Chinese (Mandarin)、English |
description | string | 否 | 音色描述 |
7.2 Prompt 写法建议
建议在 prompt 中描述这些信息:
| 维度 | 示例 |
|---|---|
| 语言 | Chinese Mandarin、English、Cantonese |
| 性别 | male、female |
| 年龄感 | young adult、middle-aged、elder |
| 声音质感 | warm、clear、soft、energetic、calm |
| 场景 | product demo、customer service、audiobook、game character |
| 情绪 | friendly、confident、gentle、dramatic |
| 节奏 | slow、medium pace、lively |
7.3 中文温柔旁白
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A warm, calm Chinese Mandarin female narrator voice for short product demos, clear diction, gentle confidence, studio quality.",
"preview_text": "你好,这是一段声音设计预览。欢迎体验全新的语音能力。",
"display_name": "warm-product-narrator",
"language": "Chinese (Mandarin)",
"description": "适合产品讲解和短视频口播的温柔女声"
}'
7.4 数字人口播音色
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A confident Chinese Mandarin female digital human presenter voice, natural conversational tone, bright but not exaggerated, suitable for business explanation videos.",
"preview_text": "大家好,我是你的智能讲解员。今天我们用一分钟了解这个功能。",
"display_name": "digital-human-presenter",
"language": "Chinese (Mandarin)",
"description": "数字人讲解员音色"
}'
7.5 客服播报音色
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A polite Chinese Mandarin customer service voice, patient, clear, stable, friendly, suitable for service notifications and call center messages.",
"preview_text": "您好,您的订单已经处理完成。如有疑问,请随时联系我们的客服团队。",
"display_name": "customer-service-clear",
"language": "Chinese (Mandarin)",
"description": "客服通知和电话播报音色"
}'
7.6 游戏角色音色
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A young Chinese Mandarin fantasy game character voice, playful, lively, slightly mysterious, expressive but clear.",
"preview_text": "终于等到你了。前面的路可不简单,跟紧我,我们马上出发。",
"display_name": "fantasy-guide-character",
"language": "Chinese (Mandarin)",
"description": "游戏引导角色音色"
}'
7.7 英文广告音色
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A modern English commercial voice, energetic, premium, confident, suitable for product launch ads and social media videos.",
"preview_text": "Meet the new way to create, edit, and publish your ideas in minutes.",
"display_name": "english-commercial-premium",
"language": "English",
"description": "English commercial voice for product ads"
}'
7.8 有声书旁白音色
curl -X POST "https://api.xxx.xx/v1/audio/voices/design" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A mature Chinese Mandarin audiobook narrator voice, calm, steady, immersive, with clear pronunciation and comfortable pacing.",
"preview_text": "夜色慢慢落下,远处的灯光一盏接一盏亮起,故事也从这里开始。",
"display_name": "audiobook-calm-narrator",
"language": "Chinese (Mandarin)",
"description": "有声书长篇旁白音色"
}'
7.9 响应示例
{
"object": "audio.voice",
"model": "minimax-voice-design",
"task_id": "task_437fb17536aa4ff7830ffb7a39f43a99",
"voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
"preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
"voice": {
"voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
"display_name": "warm-product-narrator",
"language": "Chinese (Mandarin)",
"description": "适合产品讲解和短视频口播的温柔女声",
"source_type": "voice_design",
"visibility": "private",
"status": "active",
"compatible_models": [
"minimax-speech-2.8-hd",
"minimax-speech-02-hd"
],
"preview_audio_url": "https://api.xxx.xx/media/design-preview.mp3",
"created_at": "2026-06-24T08:42:23Z"
},
"billing_contract": {
"billing_version": "media-v1",
"public_model": "minimax-voice-design",
"operation": "audio.voice_design",
"settlement_policy": "fixed_at_estimate",
"billing_stage": "final",
"facts": {
"voice_designs": 1,
"preview_characters": 12
}
},
"outputs": [
{
"url": "https://api.xxx.xx/media/design-preview.mp3",
"type": "audio"
}
]
}
8. 将 voice_id 用于语音生成
声音克隆或声音设计成功后,把返回的 voice_id 放到 /v1/audio/tasks 中即可生成语音。
8.1 使用声音设计音色生成中文口播
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-speech-2.8-hd",
"text": "欢迎来到今天的产品演示。接下来,我们会快速了解三个核心功能。",
"voice_id": "ttv-voice-2026062416421526-E4jmMP8B",
"speed": 1.0,
"response_format": "url"
}'
8.2 使用声音克隆音色生成课程讲解
curl -X POST "https://api.xxx.xx/v1/audio/tasks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-speech-02-hd",
"text": "本节课我们来学习一个非常重要的概念。请先观察这个例子,再思考它背后的规律。",
"voice_id": "VoiceClone123456",
"speed": 0.95,
"response_format": "url"
}'
8.3 查询语音生成任务
curl "https://api.xxx.xx/v1/audio/tasks/task_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
8.4 语音生成任务完成响应示例
{
"object": "audio.generation.job",
"task_id": "task_abc123",
"model": "minimax-speech-2.8-hd",
"status": "completed",
"audio_url": "https://api.xxx.xx/media/output.mp3",
"result": {
"audio_url": "https://api.xxx.xx/media/output.mp3",
"outputs": [
"https://api.xxx.xx/media/output.mp3"
],
"audios": [
{
"url": "https://api.xxx.xx/media/output.mp3"
}
]
}
}
9. 计费说明
实际扣费以 aijisu 控制台展示和账户配置为准。以下为当前接口的基础计费口径。
| 能力 | 计费项 | 基础计费公式 |
|---|---|---|
| 查询音色列表 | 免费 | 不扣费 |
| 声音克隆 | 克隆次数 + 预览字符 | voice_clones * 1.5 + preview_characters * 0.0003 |
| 声音设计 | 设计次数 + 预览字符 | voice_designs * 3 + preview_characters * 0.00003 |
| 语音生成 | 输入字符数 | 按 TTS 模型的字符计费规则 |
说明:
preview_characters是预览文本的 Unicode 字符数。- 中文、英文、空格、标点、换行、emoji 都会计入字符数。
- 字符数不是 UTF-8 字节数,也不是 token 数。
- 声音克隆和声音设计采用提交时确认计费策略。
- 如果请求失败,按平台失败退款规则处理。
10. Node.js 示例
10.1 声音设计
const response = await fetch("https://api.xxx.xx/v1/audio/voices/design", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
prompt: "A warm Chinese Mandarin female narrator voice, clear and calm.",
preview_text: "你好,这是声音设计预览。",
display_name: "node-design-voice",
language: "Chinese (Mandarin)"
})
});
const data = await response.json();
console.log(data.voice_id);
console.log(data.preview_audio_url);
10.2 用生成的 voice_id 创建语音任务
const voiceId = "ttv-voice-2026062416421526-E4jmMP8B";
const response = await fetch("https://api.xxx.xx/v1/audio/tasks", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "minimax-speech-2.8-hd",
text: "这是一段使用自定义音色生成的语音。",
voice_id: voiceId,
response_format: "url"
})
});
const task = await response.json();
console.log(task.task_id);
11. Python 示例
11.1 声音克隆
import requests
api_key = "YOUR_API_KEY"
response = requests.post(
"https://api.xxx.xx/v1/audio/voices/clone",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"audio_url": "https://example.com/audio/reference-speaker.mp3",
"text": "大家好,欢迎来到今天的课程。",
"display_name": "python-clone-voice",
"language": "Chinese (Mandarin)",
"noise_reduction": True,
"need_volume_normalization": True,
},
timeout=180,
)
data = response.json()
print(data["voice_id"])
print(data.get("preview_audio_url"))
11.2 查询音色列表
import requests
api_key = "YOUR_API_KEY"
response = requests.get(
"https://api.xxx.xx/v1/audio/voices",
headers={"Authorization": f"Bearer {api_key}"},
params={"model": "minimax-speech-2.8-hd"},
timeout=30,
)
voices = response.json()["data"]
for voice in voices:
print(voice["voice_id"], voice.get("display_name"))
12. 常见错误
12.1 缺少鉴权
{
"error": {
"message": "API key required.",
"type": "invalid_request_error",
"code": "api_key_required"
}
}
解决方法:检查请求头是否包含 Authorization: Bearer YOUR_API_KEY。
12.2 声音克隆缺少 audio_url
{
"error": {
"message": "`audio_url` is required.",
"type": "invalid_request_error",
"code": "invalid_request_parameter"
}
}
解决方法:传入可公网访问的参考音频 URL。
12.3 声音设计缺少 prompt
{
"error": {
"message": "`prompt` is required.",
"type": "invalid_request_error",
"code": "invalid_request_parameter"
}
}
解决方法:补充声音描述,例如性别、语言、场景、情绪、语速和质感。
12.4 声音设计缺少 preview_text
{
"error": {
"message": "`preview_text` is required.",
"type": "invalid_request_error",
"code": "invalid_request_parameter"
}
}
解决方法:传入用于生成预览音频的文本。
12.5 voice_id 不可用
{
"error": {
"message": "`voice_id` is not visible for the current client or is not compatible with this model",
"type": "invalid_request_error",
"code": "invalid_request_parameter"
}
}
可能原因:
voice_id拼写错误。- 当前账号无权使用该私有音色。
- 该音色不兼容当前 TTS 模型。
- 音色已被禁用或不可用。
解决方法:
- 先调用
GET /v1/audio/voices?model=...查询可用音色。 - 从返回结果中复制
voice_id。 - 再将该
voice_id用到/v1/audio/tasks。
13. 最佳实践
13.1 什么时候用声音克隆
当你已经有参考音频,并且需要复刻某个真实声音时,使用声音克隆。
典型场景:
- 已有主播录音。
- 已有讲师试听音频。
- 已有品牌代言人授权音频。
- 想让后续 TTS 尽量接近参考声音。
13.2 什么时候用声音设计
当你没有参考音频,但能描述想要的声音时,使用声音设计。
典型场景:
- 设计一个数字人声音。
- 为短视频账号生成品牌音色。
- 为游戏角色生成声音。
- 快速试出多种广告或客服音色。
13.3 音色命名建议
建议给 display_name 使用稳定、可读、可搜索的名称。
示例:
brand-female-presenter
course-teacher-male
customer-service-clear
game-guide-young
english-commercial-premium
13.4 保存 voice_id
创建成功后,请保存:
voice_iddisplay_namesource_typepreview_audio_urlcompatible_modelscreated_at
其中最重要的是 voice_id。后续 TTS 调用只需要传 voice_id。
13.5 生产环境调用建议
- 声音克隆和声音设计通常比普通 TTS 更慢,建议客户端设置较长超时时间。
- 不要在前端暴露 API Key。
- 建议由服务端调用 aijisu API。
- 对
voice_id做业务侧保存,避免重复创建相同音色。 - 创建前确认音频和声音授权,避免克隆无授权声音。