> ## Documentation Index > Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt > Use this file to discover all available pages before exploring further. # MiniMax Speech 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={task_id} | | Subir archivo | POST /v3/minimax/v1/files/upload | | Consultar archivo | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} | | Descargar archivo | GET /v3/minimax/v1/files/retrieve\_content?file\_id={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 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](https://platform.minimaxi.com/docs/api-reference/speech-t2a-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 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_v2' \ -H 'Authorization: Bearer ' \ -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 ```json theme={null} { "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](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create), [Consultar tarea asíncrona](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query) ### 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 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/t2a_async_v2' \ -H 'Authorization: Bearer ' \ -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 } }' ``` ```json theme={null} { "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 ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \ -H 'Authorization: Bearer ' ``` 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. ```json theme={null} { "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](https://platform.minimaxi.com/docs/api-reference/file-management-upload), [Consulta de archivos](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve), [Descarga de archivos](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content) ### 4.1 Subir archivo ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/files/upload' \ -H 'Authorization: Bearer ' \ -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 ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve?file_id=95157322514496' \ -H 'Authorization: Bearer ' curl -X GET 'https://{api_domain}/v3/minimax/v1/files/retrieve_content?file_id=95157322514496' \ -H 'Authorization: Bearer ' \ --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](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone) ### 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 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_clone' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "file_id": 123456789, "voice_id": "MyVoice001", "need_noise_reduction": false, "need_volume_normalization": false }' ``` ```json theme={null} { "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](https://platform.minimaxi.com/docs/api-reference/voice-design-design) ### 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 ```bash theme={null} curl -X POST 'https://{api_domain}/v3/minimax/v1/voice_design' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "prompt": "A warm, clear adult narrator with a calm delivery.", "preview_text": "Welcome to our service." }' ``` ```json theme={null} { "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. ```python theme={null} 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) ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.