POST
/minimax/v1/voice_design音色设计
API Key application/json
MiniMax 音色设计
调用与返回说明
根据文字描述生成自定义音色和试听音频。试听文本最多 500 字符，生成试听会按官方价格计费。
请求时注意
- 请求头使用 `Authorization: Bearer YOUR_API_KEY`；客户端只提交青云TOP API Key，不提交 MiniMax 上游密钥。
- 本文路径是青云TOP 的公开入口。它与 MiniMax 官方路径可能不同；以页面显示的完整本站 URL 为准，不要把官方域名或 `/v2` 自动拼到本站路径。
- 官方模型存在不等于当前 API Key 已开放。调用前请求 `GET /v1/models`，再结合分组权限、当前 pricing 和实际错误响应确认型号；生产 pricing 快照未覆盖全部官方 speech/H3 型号。
- prompt 与 preview_text 必填；可选传入自定义 voice_id，否则服务端生成唯一 ID。
- 不要把试听 hex 音频当作永久 URL；按格式解码后保存。
返回时注意
- HTTP 2xx 只表示请求被网关接受；还要检查响应体中的 `base_resp.status_code`、任务 `status` 或 Responses/兼容协议的业务字段。
- 官方临时音频、视频和文件 URL 有效期有限。成功后立即下载或转存到自己的对象存储，不要把示例地址当作永久资源。
- 余额、分组权限、内容安全、限流和模型下线都可能导致业务失败；记录 trace/request ID 和完整错误信息，按退避策略重试。
- 保存 voice_id 供后续 TTS 使用，并检查 base_resp.status_code。
Request
请求
/minimax/v1/voice_designBody
必填Bodyobjectpromptstring必填音色描述。
示例
声音低沉、有磁性的悬疑故事播音员。preview_textstring必填试听文本，最多 500 字符。
示例
夜深了，古屋里只有他一人。voice_idstring可选，自定义音色 ID。
aigc_watermarkboolean是否添加音频节奏标识。
路径、查询与 Header 参数
| 参数 | 位置 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|---|
Content-Type | Header | string | 否 | - | application/json |
Authorization | Header | string | 是 | 必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。 | Bearer YOUR_API_KEY |
Response返回响应
成功响应返回响应 200
响应 200objectvoice_idstring生成的音色 ID。
trial_audiostring试听音频 hex 数据。
base_respobject
base_respobjectstatus_codeinteger业务状态码。
status_msgstring状态描述。
MiniMax 音色设计
调用与返回说明
根据文字描述生成自定义音色和试听音频。试听文本最多 500 字符，生成试听会按官方价格计费。
请求时注意
- 请求头使用 `Authorization: Bearer YOUR_API_KEY`；客户端只提交青云TOP API Key，不提交 MiniMax 上游密钥。
- 本文路径是青云TOP 的公开入口。它与 MiniMax 官方路径可能不同；以页面显示的完整本站 URL 为准，不要把官方域名或 `/v2` 自动拼到本站路径。
- 官方模型存在不等于当前 API Key 已开放。调用前请求 `GET /v1/models`，再结合分组权限、当前 pricing 和实际错误响应确认型号；生产 pricing 快照未覆盖全部官方 speech/H3 型号。
- prompt 与 preview_text 必填；可选传入自定义 voice_id，否则服务端生成唯一 ID。
- 不要把试听 hex 音频当作永久 URL；按格式解码后保存。
返回时注意
- HTTP 2xx 只表示请求被网关接受；还要检查响应体中的 `base_resp.status_code`、任务 `status` 或 Responses/兼容协议的业务字段。
- 官方临时音频、视频和文件 URL 有效期有限。成功后立即下载或转存到自己的对象存储，不要把示例地址当作永久资源。
- 余额、分组权限、内容安全、限流和模型下线都可能导致业务失败；记录 trace/request ID 和完整错误信息，按退避策略重试。
- 保存 voice_id 供后续 TTS 使用，并检查 base_resp.status_code。