跳到主要内容
AI
MarkdownLLMs.txt

MiniMax Speech 音色管理

本文档介绍如何在 aijisu 中使用 MiniMax 音色能力,包括音色列表、声音克隆和声音设计。

如果你只是想把文字生成语音,请使用语音生成接口:

  • POST /v1/audio/tasks
  • GET /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/tasksvoice_id 传给 TTS 模型生成音频

当前推荐配合以下 TTS 模型使用:

模型名称说明
minimax-speech-2.8-hd更新一代高清语音生成模型,适合自然口播、短视频、数字人、广告配音
minimax-speech-02-hd稳定高清语音生成模型,适合旁白、有声书、课程、客服、长文本播报

声音克隆和声音设计创建出来的 voice_id 可以在以上两个 TTS 模型中使用。

2. 接口地址

示例域名统一使用:

https://api.xxx.xx

实际调用时请替换为你的 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

可选查询参数:

参数类型是否必填说明
modelstring按兼容模型筛选音色,可选 minimax-speech-2.8-hdminimax-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音色来源,可能是 systemvoice_clonevoice_design
data[].visibility可见性,可能是 publicprivate
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_urlstring参考音频 URL,需要接口服务可访问
textstring建议参考音频对应文本或预览文本,用于提升克隆质量和生成预览
preview_textstringtext 的兼容字段。若同时传,建议与 text 保持一致
display_namestring音色名称,便于列表展示
namestringdisplay_name 的兼容字段
languagestring音色语言,例如 Chinese (Mandarin)English
descriptionstring音色描述
noise_reductionboolean是否启用降噪
need_volume_normalizationboolean是否进行音量归一化
accuracynumber/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。

参数类型是否必填说明
promptstring声音设计描述,描述音色、性别、年龄感、语言、情绪、场景等
preview_textstring用于生成预览音频的文本
textstringpreview_text 的兼容字段
display_namestring音色名称,便于列表展示
namestringdisplay_name 的兼容字段
languagestring音色语言,例如 Chinese (Mandarin)English
descriptionstring音色描述

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 模型。
  • 音色已被禁用或不可用。

解决方法:

  1. 先调用 GET /v1/audio/voices?model=... 查询可用音色。
  2. 从返回结果中复制 voice_id
  3. 再将该 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_id
  • display_name
  • source_type
  • preview_audio_url
  • compatible_models
  • created_at

其中最重要的是 voice_id。后续 TTS 调用只需要传 voice_id

13.5 生产环境调用建议

  • 声音克隆和声音设计通常比普通 TTS 更慢,建议客户端设置较长超时时间。
  • 不要在前端暴露 API Key。
  • 建议由服务端调用 aijisu API。
  • voice_id 做业务侧保存,避免重复创建相同音色。
  • 创建前确认音频和声音授权,避免克隆无授权声音。