The MiniMax Voice Design API creates a reusable synthetic voice from a written description. You send a voice prompt and a short preview script to POST /v1/voice_design; MiniMax returns a voice_id and hex-encoded trial audio. This guide covers the exact request shape, prompt design, preview handling, published charges, the 168-hour activation rule, and safe lifecycle management.
Independent-site notice: MiniMax-AI.chat is an independent educational website and is not affiliated with, endorsed by, or operated by MiniMax. Voice Design requires a MiniMax Open Platform account, API key, and billing relationship. It is not supported by the text-only MiniMax-AI.chat demo, which does not generate audio.
Last verified: July 18, 2026. The endpoint schema, prices, retention behavior, model availability, and account limits can change. Check the official references linked below before deploying or estimating spend.
MiniMax Voice Design API quick facts
| Item | Documented behavior |
|---|---|
| Endpoint | POST https://api.minimax.io/v1/voice_design |
| Authentication | Server-side Bearer API key |
| Required inputs | prompt and preview_text |
| Preview limit | preview_text has a maximum length of 500 characters |
| Optional input | A custom voice_id; MiniMax creates one when omitted |
| Success output | voice_id, hex-encoded trial_audio, and base_resp |
| Published rate limit | 20 Voice Design requests per minute |
| Activation window | Use the designed voice in a speech-synthesis API within 168 hours (7 days) to retain it |
| Demo availability | Requires MiniMax Open Platform API; unavailable in the MiniMax-AI.chat text demo |
The official Voice Design reference documents the request and response. MiniMax’s broader API overview adds an important lifecycle rule: a designed voice is temporary until it is used in a T2A speech-synthesis call within 168 hours.
Voice Design is not Voice Cloning
| Route | Input | Use it when | Rights risk |
|---|---|---|---|
| Voice Design | A written voice description and preview text | You need an original synthetic persona without copying a recorded speaker | Avoid prompts that impersonate a real person or protected character |
| Voice Cloning | A recorded voice sample | You have documented permission to reproduce a specific speaker | Requires clear consent and rights for the intended uses |
| System voice | An existing MiniMax voice_id | A prebuilt voice satisfies the project brief | Confirm provider and commercial terms for your access route |
Do not describe Voice Design as cloning. The endpoint generates a voice from text direction; it does not accept a reference recording. If you need general Speech 2.8 model positioning, see our separate MiniMax Speech 2.8 guide; if you have authorized reference audio, use the distinct MiniMax voice cloning guide. This page stays focused on the design endpoint and its lifecycle.
Request fields and response fields
Required request fields
prompt: a natural-language description of the desired voice. The reference marks this field required but does not publish a character limit for it. Do not invent a limit in client validation.preview_text: the exact text used to generate the trial audio. It is required and limited to 500 characters.
Optional request field
voice_id lets you propose an identifier. If you omit it, MiniMax returns an automatically generated ID. Treat this identifier as an account resource, not a public secret. Check for collisions and never assume that a deleted ID can be registered again.
Response fields
voice_id: the designed voice identifier for later speech synthesis.trial_audio: preview audio returned as a hexadecimal string.base_resp: MiniMax’s application-level status code and message. A successful HTTP status alone is not enough; checkbase_resp.status_code.
How to write a useful voice design prompt
The API exposes the voice description as one free-text field, not a set of guaranteed sub-parameters. A structured sentence still makes creative intent easier to review. Describe the role, vocal character, delivery, pace, energy, diction, and intended listening context. Treat these as directions to evaluate, not deterministic controls.
Warm adult educational narrator; calm, confident delivery; medium pace;
clear diction; restrained energy; natural pauses; suitable for a concise
software tutorial; avoid a theatrical or sales-like performance.Avoid celebrity names, living-person impersonation requests, unsupported claims such as “perfectly identical,” and contradictory directions such as “very slow and extremely fast.” If a regional accent matters, name it as a preference and require review by a fluent listener; do not promise native authenticity before hearing the output.
Choose preview text that reveals problems
A preview should test the actual production risk. Include a short greeting, a question, a sentence with emphasis, one number, and any brand or technical term that matters. Keep it below 500 characters and do not paste customer records, unreleased scripts, personal identifiers, credentials, or regulated data.
Welcome to Northstar Learning. In this lesson, we will configure three
settings, verify the result, and explain what to do if the request fails.
Ready to begin?Node.js: create a designed voice and decode the preview
Run this example on a trusted server. It reads the API key from the environment, validates both HTTP and MiniMax-level errors, verifies the hex response, and stores the raw preview bytes. The Voice Design response schema does not state the preview’s audio container, so the example uses a neutral .bin extension instead of pretending it is MP3 or WAV.
import { writeFile } from "node:fs/promises";
const API_KEY = process.env.MINIMAX_API_KEY;
if (!API_KEY) {
throw new Error("Set MINIMAX_API_KEY in the server environment.");
}
const response = await fetch("https://api.minimax.io/v1/voice_design", {
method: "POST",
headers: {
Authorization: "Bearer " + API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
prompt:
"Warm adult educational narrator; calm, confident delivery; " +
"medium pace; clear diction; restrained energy; natural pauses.",
preview_text:
"Welcome to Northstar Learning. We will configure three settings, " +
"verify the result, and explain what to do if the request fails."
})
});
const raw = await response.text();
let data;
try {
data = JSON.parse(raw);
} catch {
throw new Error("MiniMax returned non-JSON data (HTTP " + response.status + ").");
}
if (!response.ok) {
throw new Error("MiniMax HTTP " + response.status + ": " + raw);
}
if (data?.base_resp?.status_code !== 0) {
throw new Error(
"MiniMax error " + data?.base_resp?.status_code + ": " +
(data?.base_resp?.status_msg || "Unknown error")
);
}
if (!data.voice_id) {
throw new Error("The response did not contain voice_id.");
}
if (!/^(?:[0-9a-fA-F]{2})+$/.test(data.trial_audio || "")) {
throw new Error("trial_audio was missing or was not valid hexadecimal data.");
}
await writeFile("voice-design-preview.bin", Buffer.from(data.trial_audio, "hex"));
console.log(JSON.stringify({ voice_id: data.voice_id }, null, 2));Inspect the first bytes or use a media-identification tool before assigning an extension and MIME type. Do not log trial_audio in production: it is large, can expose unreleased creative material, and adds noise to observability systems.
Python: equivalent Voice Design request
import os
from pathlib import Path
import requests
api_key = os.environ.get("MINIMAX_API_KEY")
if not api_key:
raise RuntimeError("Set MINIMAX_API_KEY in the server environment.")
response = requests.post(
"https://api.minimax.io/v1/voice_design",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json={
"prompt": (
"Warm adult educational narrator; calm, confident delivery; "
"medium pace; clear diction; restrained energy; natural pauses."
),
"preview_text": (
"Welcome to Northstar Learning. We will configure three settings, "
"verify the result, and explain what to do if the request fails."
),
},
timeout=60,
)
response.raise_for_status()
data = response.json()
base_resp = data.get("base_resp") or {}
if base_resp.get("status_code") != 0:
raise RuntimeError(
f"MiniMax error {base_resp.get('status_code')}: "
f"{base_resp.get('status_msg', 'Unknown error')}"
)
voice_id = data.get("voice_id")
trial_hex = data.get("trial_audio")
if not voice_id or not trial_hex:
raise RuntimeError("The response is missing voice_id or trial_audio.")
try:
preview_bytes = bytes.fromhex(trial_hex)
except ValueError as exc:
raise RuntimeError("trial_audio is not valid hexadecimal data.") from exc
Path("voice-design-preview.bin").write_bytes(preview_bytes)
print({"voice_id": voice_id})Activate and retain the designed voice
Previewing a design is not the same as retaining it. MiniMax states that the generated voice is temporary and must be used in any T2A speech-synthesis API within 168 hours. The design fee is charged on that first synthesis use. A successful call to POST /v1/t2a_v2 with the returned voice_id activates the voice; it also incurs normal T2A usage charges.
const activation = await fetch("https://api.minimax.io/v1/t2a_v2", {
method: "POST",
headers: {
Authorization: "Bearer " + process.env.MINIMAX_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "speech-2.8-turbo",
text: "This short, approved line activates the designed voice.",
stream: false,
output_format: "hex",
voice_setting: {
voice_id: "REPLACE_WITH_RETURNED_VOICE_ID",
speed: 1,
vol: 1,
pitch: 0
},
audio_setting: {
sample_rate: 32000,
bitrate: 128000,
format: "mp3",
channel: 1
}
})
});
const activationData = await activation.json();
if (!activation.ok || activationData?.base_resp?.status_code !== 0) {
throw new Error("Activation failed: " + JSON.stringify(activationData));
}The official T2A HTTP reference documents this synthesis endpoint. For live delivery, use the separate MiniMax WebSocket TTS guide; for books or other long inputs, use the MiniMax Async TTS guide.
Voice Design cost and rate limits
| Billing item | Published price checked July 18, 2026 | When it matters |
|---|---|---|
| Voice Design | $3 per voice | The API overview says the generation fee is charged on first T2A use of the designed voice |
| Preview generation | $30 per 1 million preview characters | The Voice Design endpoint places this note on preview_text |
speech-2.8-turbo T2A | $60 per 1 million characters | Separate synthesis usage, including activation |
speech-2.8-hd T2A | $100 per 1 million characters | Separate synthesis usage, including activation |
At the documented 500-character preview maximum, $30 per million characters equals $0.015 for the preview text itself. That calculation excludes the $3-per-voice item, later T2A usage, taxes, credits, subscription allowances, or account-specific arrangements. The official pay-as-you-go table is the source of record; our MiniMax pricing guide explains the site’s wider pricing methodology. MiniMax’s rate-limit table lists Voice Design at 20 RPM; implement backoff for rate-limit responses rather than retrying immediately.
Production voice lifecycle checklist
- Define an original voice brief and prohibited traits.
- Generate one small preview and record the prompt version, preview text, request time, and returned
voice_id. - Have an editor review intelligibility, persona fit, pronunciation, artifacts, and impersonation risk.
- Reject unsuitable designs without activating them.
- For an approved voice, run one authorized T2A synthesis within 168 hours.
- Store the active
voice_idin a server-side configuration or secrets system, not in page markup. - Query account voices with
voice_type: "voice_generation"when auditing inventory. - Delete unused voices through the management API after confirming no production job references them.
The Get Voice reference says designed voices appear under voice_generation only after successful speech synthesis. The Delete Voice reference uses the same type for deletion and warns that deletion is irreversible and the deleted voice_id cannot be reused.
Security, consent, and editorial controls
- Keep keys server-side: never embed a MiniMax API key in WordPress, client-side JavaScript, a public repository, or an audio player.
- Do not impersonate: a text-designed voice can still be directed toward a recognizable person. Require an original brief and a documented review.
- Use approved text: preview and activation lines should contain no credentials, customer data, medical records, private scripts, or unreleased financial information.
- Disclose synthetic audio where appropriate: do not let audiences reasonably believe a synthetic voice is a real speaker.
- Control deletion: check dependencies before deleting a voice because the ID cannot be reused.
- Review applicable terms: commercial and regulated use depends on MiniMax terms, your speaker or client agreements, distribution-platform rules, and applicable law.
For the site’s handling boundaries, read Security and the Privacy Policy. For the wider endpoint map, see the MiniMax API documentation hub and MiniMax audio guide. For API failures, use the MiniMax API error guide rather than exposing raw provider responses to end users.
Frequently asked questions
Does Voice Design require an audio sample?
No. The endpoint takes a written prompt and preview_text. A reference recording belongs to the separate Voice Cloning workflow.
How long can the preview text be?
The official endpoint reference sets the maximum preview_text length at 500 characters.
Is the designed voice retained automatically?
No. MiniMax describes the generated voice as temporary until it is used in a T2A synthesis API within 168 hours. Plan approval and activation before that window closes.
What format is trial_audio?
The response reference identifies it as hex-encoded audio but does not name the underlying container. Decode the hex and inspect the bytes before assigning a filename extension or MIME type.
Can the MiniMax-AI.chat demo design a voice?
No. This workflow requires the official MiniMax Open Platform API and the user’s own API key and billing account.
Sources and verification scope
This page distinguishes endpoint documentation from editorial recommendations. Exact API fields, prices, rate limits, and the 168-hour rule were checked against the linked MiniMax sources. Prompt structure, security controls, consent review, and lifecycle governance are implementation recommendations and should be adapted to your organization.
More on speech: see the MiniMax Audio hub for voices, voice cloning, text-to-speech pricing and which speech model to choose.