MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

minimax

t2a_v2

MiniMax Speech

curl --request POST \
  --url https://{api_domain}/v3/minimax/v1/t2a_v2

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/minimax/v1/t2a_v2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/minimax/v1/t2a_v2"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/minimax/v1/t2a_v2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Los parámetros y el modo de uso están alineados con los del proveedor oficial; para los parámetros detallados, consulte directamente la documentación oficial.

I. Descripción general

Este documento explica cómo usar la síntesis de voz síncrona, la síntesis de voz asíncrona para textos largos, la gestión de archivos, la clonación rápida de voz y el diseño de voz mediante el protocolo original de MiniMax. La interfaz síncrona devuelve audio o SSE directamente en una única solicitud POST; la interfaz asíncrona devuelve primero task_id, el cliente consulta después el estado de la tarea y obtiene el archivo de resultado mediante file_id.

1.1 Direcciones de la API

Capacidad	Método y ruta
Síntesis de voz síncrona	POST /v3/minimax/v1/t2a_v2
Crear tarea de voz asíncrona	POST /v3/minimax/v1/t2a_async_v2
Consultar tarea de voz asíncrona	GET /v3/minimax/v1/query/t2a_async_query_v2?task_id=
Subir archivo	POST /v3/minimax/v1/files/upload
Consultar archivo	GET /v3/minimax/v1/files/retrieve?file_id=
Descargar archivo	GET /v3/minimax/v1/files/retrieve_content?file_id=
Clonación rápida de voz	POST /v3/minimax/v1/voice_clone
Diseño de voz	POST /v3/minimax/v1/voice_design

La dirección completa es https://{api_domain} más la ruta de la tabla, donde {api_domain} es el dominio de API que utiliza.

1.2 Autenticación

Todas las solicitudes requieren una API Key de la plataforma. Las solicitudes POST JSON también deben especificar el tipo de contenido:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

La carga de archivos usa multipart/form-data; las solicitudes GET no requieren Content-Type.

1.3 Respuestas y acceso a recursos

Las interfaces conservan los campos de respuesta y la estructura de errores originales de MiniMax. Las respuestas JSON suelen incluir base_resp.status_code y base_resp.status_msg; un HTTP 200 no necesariamente indica éxito de negocio, compruebe siempre base_resp.status_code=0. task_id y file_id pueden superar el rango de enteros seguros de JavaScript; guárdelos como enteros sin pérdida o como cadenas. Los archivos, las tareas y las voces privadas solo pueden ser accedidos por el usuario de la plataforma que los creó; al consultar, utilice la misma API Key de la plataforma con la que creó el recurso.

II. Síntesis de voz síncrona

Documentación oficial de parámetros: Síntesis de voz síncrona HTTP

2.1 Llamada a la interfaz

POST https://{api_domain}/v3/minimax/v1/t2a_v2

Campos de solicitud habituales:

Campo	Tipo	Obligatorio	Descripción
model	string	Sí	speech-2.8-hd o speech-2.8-turbo
text	string	Sí	Texto a sintetizar, menos de 10.000 caracteres; si supera los 3.000 caracteres, se recomienda salida en streaming
stream	boolean	No	Indica si se devuelve SSE del proveedor original; predeterminado false
voice_setting	object	Sí	Configuración de voz, velocidad, volumen, tono y emoción, etc.
audio_setting	object	No	Configuración de audio: frecuencia de muestreo, bitrate, formato y canales
language_boost	string	No	Idioma especificado o auto
output_format	string	No	hex (predeterminado) o url; el streaming solo admite hex; la URL es válida durante 24 horas
subtitle_enable	boolean	No	Indica si se devuelven subtítulos; predeterminado false

Los campos extendidos del proveedor original, como pronunciation_dict, timbre_weights, voice_modify y stream_options, se reenvían tal cual; para las restricciones detalladas, consulte la documentación oficial de MiniMax.

2.2 Ejemplo de llamada

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-hd",
    "text": "Welcome to our service.",
    "stream": false,
    "voice_setting": {
      "voice_id": "male-qn-qingse",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    },
    "output_format": "url"
  }'

Para una llamada en streaming, solo hay que establecer stream=true y usar un cliente que admita lectura en streaming, por ejemplo curl -N.

2.3 Descripción de la respuesta

{
  "data": {
    "audio": "https://example.com/audio.mp3",
    "status": 2
  },
  "extra_info": {
    "usage_characters": 26,
    "audio_length": 9900,
    "audio_format": "mp3"
  },
  "trace_id": "provider-trace-id",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

La respuesta en streaming es SSE del proveedor original. En el evento final exitoso, data.status es 2 y el uso se encuentra en extra_info.usage_characters.

2.4 Facturación

Se factura según extra_info.usage_characters devuelto finalmente por el proveedor; la unidad de facturación es cada 10.000 caracteres. Las solicitudes fallidas, los errores de negocio del proveedor original y los SSE sin evento de finalización exitoso no se cobran. El precio unitario concreto se rige por la página de precios del servicio que utilice.

III. Síntesis de voz asíncrona para textos largos

Documentación oficial de parámetros: Crear tarea asíncrona, Consultar tarea asíncrona

3.1 Crear tarea

POST https://{api_domain}/v3/minimax/v1/t2a_async_v2

Campo	Tipo	Obligatorio	Descripción
model	string	Sí	speech-2.8-hd o speech-2.8-turbo
text	string	Elija uno	Texto a sintetizar, máximo 50.000 caracteres; elija entre text y text_file_id
text_file_id	integer	Elija uno	ID obtenido mediante la carga de archivos; admite txt o zip; el texto de un solo archivo debe tener menos de 1.000.000 de caracteres
voice_setting	object	Sí	Configuración de voz y parámetros de voz
audio_setting	object	No	Configuración de audio de salida
language_boost	string	No	Idioma especificado o auto

3.2 Ejemplo de creación

curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_async_v2' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "speech-2.8-turbo",
    "text": "A longer narration.",
    "voice_setting": {
      "voice_id": "audiobook_male_1",
      "speed": 1,
      "vol": 1,
      "pitch": 0
    }
  }'

{
  "task_id": 95157322514444,
  "task_token": "provider-task-token",
  "file_id": 95157322514444,
  "usage_characters": 101,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Guarde task_id. La creación correcta de una tarea asíncrona se cobra en el momento según usage_characters de la respuesta; las consultas posteriores no se cobran de nuevo.

3.3 Consultar tarea

curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

Esta interfaz de consulta admite como máximo 10 llamadas por segundo. Los estados incluyen Processing, Success, Failed y Expired; deje de sondear cuando se alcance un estado terminal.

{
  "task_id": 95157322514444,
  "status": "Success",
  "file_id": 95157322514496,
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Una vez que la tarea se complete correctamente, use file_id para consultar o descargar el archivo. La documentación oficial de MiniMax indica que la URL de descarga es válida durante aproximadamente 9 horas desde su generación; guarde el resultado a tiempo.

IV. Gestión de archivos

Documentación oficial de parámetros: Carga de archivos, Consulta de archivos, Descarga de archivos

4.1 Subir archivo

curl -X POST 'https://{api_domain}/v3/minimax/v1/files/upload' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -F 'purpose=voice_clone' \
  -F 'file=@voice.wav'

purpose	Uso y formato
voice_clone	Audio original para clonación rápida; mp3, m4a, wav
prompt_audio	Audio de ejemplo para clonación de voz; mp3, m4a, wav
t2a_async_input	Entrada de texto largo asíncrona; txt, zip

La solicitud debe contener obligatoriamente un único purpose y un único archivo. El límite del cuerpo de una solicitud a la plataforma es de 64 MiB; siguen aplicándose las restricciones de formato, duración y tamaño de MiniMax para cada uso.

4.2 Consultar y descargar

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve_content?file_id=95157322514496' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  --output result.mp3

retrieve devuelve los metadatos del archivo y download_url; retrieve_content devuelve directamente el archivo binario. La carga, la consulta y la descarga no se cobran.

V. Clonación rápida de voz

Documentación oficial de parámetros: Clonación rápida de voz

5.1 Llamada a la interfaz y campos

POST https://{api_domain}/v3/minimax/v1/voice_clone

Campo	Tipo	Obligatorio	Descripción
file_id	integer	Sí	ID de archivo obtenido mediante la carga con purpose=voice_clone; el audio debe durar entre 10 segundos y 5 minutos y no superar los 20 MB
voice_id	string	Sí	ID de voz personalizado, longitud 8–256, debe comenzar por una letra y no debe repetir un ID existente
clone_prompt	object	No	Audio de ejemplo; si se usa, prompt_audio y prompt_text son obligatorios
text	string	No	Texto de prueba, máximo 1.000 caracteres
model	string	Obligatorio condicionalmente	Obligatorio si se pasa text; use speech-2.8-hd o speech-2.8-turbo
text_validation	string	No	Texto esperado de la muestra, máximo 200 caracteres
accuracy	number	No	Umbral de similitud ASR, 0–1, predeterminado 0.7

5.2 Ejemplo de llamada y respuesta

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_clone' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "file_id": 123456789,
    "voice_id": "MyVoice001",
    "need_noise_reduction": false,
    "need_volume_normalization": false
  }'

{
  "input_sensitive": false,
  "demo_audio": "",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Una solicitud correcta se factura como una voz. Si la solicitud genera un audio de prueba, la plataforma no añade un SKU de síntesis de voz adicional. La documentación oficial de MiniMax indica que, si una voz clonada no se utiliza formalmente para síntesis de voz en un plazo de 7 días, puede eliminarse.

VI. Diseño de voz

Documentación oficial de parámetros: Diseño de voz

6.1 Llamada a la interfaz y campos

POST https://{api_domain}/v3/minimax/v1/voice_design

Campo	Tipo	Obligatorio	Descripción
prompt	string	Sí	Descripción de la voz objetivo
preview_text	string	Sí	Texto de prueba, máximo 500 caracteres
voice_id	string	No	ID de voz personalizado; si no se pasa, lo genera MiniMax
aigc_watermark	boolean	No	Indica si se añade una marca rítmica al final del audio de prueba; predeterminado false

6.2 Ejemplo de llamada y respuesta

curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_design' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A warm, clear adult narrator with a calm delivery.",
    "preview_text": "Welcome to our service."
  }'

{
  "voice_id": "ttv-voice-generated-id",
  "trial_audio": "hex-encoded-audio",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Una solicitud correcta se factura como una voz; el audio de prueba está incluido en la facturación de esta interfaz y no añade un SKU de síntesis de voz adicional.

VII. Errores comunes y consideraciones

Fenómeno	Descripción y sugerencia de tratamiento
HTTP 200, pero base_resp.status_code!=0	Error de negocio de MiniMax; corrija la entrada según status_msg y no lo trate como éxito
HTTP 400	JSON, multipart, nombre del modelo, parámetros de consulta o campos obligatorios no válidos
HTTP 401/403	Compruebe la API Key de la plataforma, el saldo y los permisos
HTTP 404	El archivo, la tarea o la voz privada no existe, o no pertenece al usuario actual de la plataforma
HTTP 429	Reduzca la frecuencia de solicitudes/consultas y use retroceso exponencial; las consultas asíncronas no deben superar las 10 por segundo
HTTP 5xx	Conserve la respuesta y el trace ID de la plataforma y contacte con soporte técnico; no reintente sin control las solicitudes de creación no idempotentes

Los campos del proveedor original se reenvían tal cual en la medida de lo posible, pero este servicio solo expone las ocho rutas enumeradas en este documento.
El límite del cuerpo de una solicitud y de un evento SSE individual es de 64 MiB.
Si el cliente se desconecta, el servicio puede seguir leyendo el SSE ya iniciado para completar la liquidación del uso.
Las tareas asíncronas deben obtener el estado a través de la interfaz de consulta de MiniMax de este documento, no mediante la interfaz genérica de resultados asíncronos de la plataforma.
Una vez recibida una URL de archivo o un ID de archivo correcto, descárguelo a tiempo; la URL y el archivo pueden caducar.

VIII. Ejemplo de llamada en Python

El siguiente ejemplo muestra la creación asíncrona y el sondeo. En producción, configure tiempos de espera globales, retroceso exponencial y un número máximo de sondeos.

import os
import time

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

created = requests.post(
    f"https://{api_domain}/v3/minimax/v1/t2a_async_v2",
    headers=headers,
    json={
        "model": "speech-2.8-turbo",
        "text": "A longer narration.",
        "voice_setting": {"voice_id": "audiobook_male_1"},
    },
    timeout=60,
)
created.raise_for_status()
created_body = created.json()
if created_body["base_resp"]["status_code"] != 0:
    raise RuntimeError(created_body)
task_id = created_body["task_id"]

while True:
    response = requests.get(
        f"https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"task_id": task_id},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()
    if task["base_resp"]["status_code"] != 0:
        raise RuntimeError(task)
    if task["status"] == "Success":
        print(task["file_id"])
        break
    if task["status"] in {"Failed", "Expired"}:
        raise RuntimeError(task)
    time.sleep(2)

Última modificación el 21 de octubre de 2026

Conceptos básicos de API

Modelos de lenguaje

Imágenes

Vídeo

Audio

MiniMax Speech

I. Descripción general

1.1 Direcciones de la API

1.2 Autenticación

1.3 Respuestas y acceso a recursos

II. Síntesis de voz síncrona

2.1 Llamada a la interfaz

2.2 Ejemplo de llamada

2.3 Descripción de la respuesta

2.4 Facturación

III. Síntesis de voz asíncrona para textos largos

3.1 Crear tarea

3.2 Ejemplo de creación

3.3 Consultar tarea

IV. Gestión de archivos

4.1 Subir archivo

4.2 Consultar y descargar

V. Clonación rápida de voz

5.1 Llamada a la interfaz y campos

5.2 Ejemplo de llamada y respuesta

VI. Diseño de voz

6.1 Llamada a la interfaz y campos

6.2 Ejemplo de llamada y respuesta

VII. Errores comunes y consideraciones

VIII. Ejemplo de llamada en Python

​I. Descripción general

​1.1 Direcciones de la API

​1.2 Autenticación

​1.3 Respuestas y acceso a recursos

​II. Síntesis de voz síncrona

​2.1 Llamada a la interfaz

​2.2 Ejemplo de llamada

​2.3 Descripción de la respuesta

​2.4 Facturación

​III. Síntesis de voz asíncrona para textos largos

​3.1 Crear tarea

​3.2 Ejemplo de creación

​3.3 Consultar tarea

​IV. Gestión de archivos

​4.1 Subir archivo

​4.2 Consultar y descargar

​V. Clonación rápida de voz

​5.1 Llamada a la interfaz y campos

​5.2 Ejemplo de llamada y respuesta

​VI. Diseño de voz

​6.1 Llamada a la interfaz y campos

​6.2 Ejemplo de llamada y respuesta

​VII. Errores comunes y consideraciones

​VIII. Ejemplo de llamada en Python

I. Descripción general

1.1 Direcciones de la API

1.2 Autenticación

1.3 Respuestas y acceso a recursos

II. Síntesis de voz síncrona

2.1 Llamada a la interfaz

2.2 Ejemplo de llamada

2.3 Descripción de la respuesta

2.4 Facturación

III. Síntesis de voz asíncrona para textos largos

3.1 Crear tarea

3.2 Ejemplo de creación

3.3 Consultar tarea

IV. Gestión de archivos

4.1 Subir archivo

4.2 Consultar y descargar

V. Clonación rápida de voz

5.1 Llamada a la interfaz y campos

5.2 Ejemplo de llamada y respuesta

VI. Diseño de voz

6.1 Llamada a la interfaz y campos

6.2 Ejemplo de llamada y respuesta

VII. Errores comunes y consideraciones

VIII. Ejemplo de llamada en Python