> ## 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 Os parâmetros e o modo de uso estão alinhados aos oficiais; para parâmetros detalhados, consulte diretamente a documentação oficial. ## 1. Visão geral Este documento explica como usar a síntese de fala síncrona, a síntese de fala assíncrona para textos longos, o gerenciamento de arquivos, a clonagem rápida de timbre e o design de timbre por meio do protocolo oficial do MiniMax Speech. A API síncrona retorna o áudio ou SSE diretamente em uma única requisição POST; a API assíncrona primeiro retorna um task\_id, e o chamador consulta o status da tarefa e obtém o arquivo de resultado por meio do file\_id. ### 1.1 Endereços das APIs | Capacidade | Método e caminho | | - | - | | Síntese de fala síncrona | POST /v3/minimax/v1/t2a\_v2 | | Criar tarefa assíncrona de fala | POST /v3/minimax/v1/t2a\_async\_v2 | | Consultar tarefa assíncrona de fala | GET /v3/minimax/v1/query/t2a\_async\_query\_v2?task\_id={task_id} | | Upload de arquivo | POST /v3/minimax/v1/files/upload | | Consultar arquivo | GET /v3/minimax/v1/files/retrieve?file\_id={file_id} | | Baixar arquivo | GET /v3/minimax/v1/files/retrieve\_content?file\_id={file_id} | | Clonagem rápida de timbre | POST /v3/minimax/v1/voice\_clone | | Design de timbre | POST /v3/minimax/v1/voice\_design | O endereço completo é https\://\{api\_domain} mais o caminho indicado na tabela, em que \{api\_domain} é o domínio da API que você usa. ### 1.2 Autenticação Todas as requisições exigem a chave de API da plataforma. Requisições POST JSON também devem especificar o tipo de conteúdo: ``` Authorization: Bearer Content-Type: application/json ``` O upload de arquivos usa multipart/form-data; requisições GET não precisam de Content-Type. ### 1.3 Respostas e acesso a recursos As APIs mantêm os campos de resposta e a estrutura de erros oficiais da MiniMax. Respostas JSON normalmente contêm base\_resp.status\_code e base\_resp.status\_msg; HTTP 200 não significa necessariamente sucesso de negócio, portanto sempre verifique base\_resp.status\_code=0. task\_id e file\_id podem exceder o intervalo de inteiros seguros do JavaScript; salve-os como inteiros sem perda ou como strings. Arquivos, tarefas e timbres privados só podem ser acessados pelo usuário da plataforma que os criou; ao consultar, use a mesma chave de API da plataforma usada na criação do recurso. ## 2. Síntese de fala síncrona Documentação oficial dos parâmetros: [Síntese de fala síncrona HTTP](https://platform.minimaxi.com/docs/api-reference/speech-t2a-http) ### 2.1 Chamar a API ``` POST https://{api_domain}/v3/minimax/v1/t2a_v2 ``` Campos comuns da requisição: | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | model | string | Sim | speech-2.8-hd ou speech-2.8-turbo | | text | string | Sim | Texto a ser sintetizado, com menos de 10.000 caracteres; acima de 3.000 caracteres, recomenda-se saída em streaming | | stream | boolean | Não | Se deve retornar o SSE oficial; padrão false | | voice\_setting | object | Sim | Configurações como ID do timbre, velocidade, volume, tom e emoção | | audio\_setting | object | Não | Configurações de taxa de amostragem, taxa de bits, formato e canal | | language\_boost | string | Não | Idioma especificado ou auto | | output\_format | string | Não | hex (padrão) ou url; o streaming só suporta hex; a URL é válida por 24 horas | | subtitle\_enable | boolean | Não | Se deve retornar legendas; padrão false | Campos de extensão oficiais como pronunciation\_dict, timbre\_weights, voice\_modify e stream\_options são encaminhados como estão; para restrições detalhadas, consulte a documentação oficial da MiniMax. ### 2.2 Exemplo de chamada ```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 chamadas em streaming, basta definir stream=true e usar um cliente que suporte leitura em streaming, por exemplo curl -N. ### 2.3 Descrição da resposta ```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" } } ``` A resposta em streaming é o SSE oficial. No evento final de sucesso, data.status é 2, e o uso fica em extra\_info.usage\_characters. ### 2.4 Cobrança A cobrança é feita com base no extra\_info.usage\_characters retornado finalmente pelo upstream, em unidades de 10.000 caracteres. Requisições com falha, erros de negócio oficiais e SSE sem evento de término bem-sucedido não são cobrados. O preço unitário específico depende da página de preços do serviço que você usa. ## 3. Síntese de fala assíncrona para textos longos Documentação oficial dos parâmetros: [Criar tarefa assíncrona](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-create), [Consultar tarefa assíncrona](https://platform.minimaxi.com/docs/api-reference/speech-t2a-async-query) ### 3.1 Criar tarefa ``` POST https://{api_domain}/v3/minimax/v1/t2a_async_v2 ``` | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | model | string | Sim | speech-2.8-hd ou speech-2.8-turbo | | text | string | Um dos dois | Texto a ser sintetizado, com no máximo 50.000 caracteres; escolha entre text e text\_file\_id | | text\_file\_id | integer | Um dos dois | Obtido via upload de arquivo; suporta txt ou zip, com menos de 1.000.000 caracteres de texto por arquivo | | voice\_setting | object | Sim | Timbre e parâmetros de fala | | audio\_setting | object | Não | Configurações do áudio de saída | | language\_boost | string | Não | Idioma especificado ou auto | ### 3.2 Exemplo de criação ```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" } } ``` Salve o task\_id. A cobrança ocorre no momento da criação bem-sucedida da tarefa assíncrona, com base no usage\_characters da resposta; consultas posteriores não geram cobrança repetida. ### 3.3 Consultar tarefa ```bash theme={null} curl -X GET 'https://{api_domain}/v3/minimax/v1/query/t2a_async_query_v2?task_id=95157322514444' \ -H 'Authorization: Bearer ' ``` Esta API de consulta permite no máximo 10 chamadas por segundo. Os estados incluem Processing, Success, Failed e Expired; pare o polling ao atingir um estado final. ```json theme={null} { "task_id": 95157322514444, "status": "Success", "file_id": 95157322514496, "base_resp": { "status_code": 0, "status_msg": "success" } } ``` Após o sucesso da tarefa, use file\_id para consultar ou baixar o arquivo. A MiniMax informa oficialmente que a URL de download é válida por cerca de 9 horas a partir da geração; salve o resultado em tempo hábil. ## 4. Gerenciamento de arquivos Documentação oficial dos parâmetros: [Upload de arquivo](https://platform.minimaxi.com/docs/api-reference/file-management-upload), [Recuperação de arquivo](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve), [Download de arquivo](https://platform.minimaxi.com/docs/api-reference/file-management-retrieve-content) ### 4.1 Upload de arquivo ```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 e formato | | - | - | | voice\_clone | Áudio original para clonagem rápida; mp3, m4a, wav | | prompt\_audio | Áudio de exemplo para clonagem de timbre; mp3, m4a, wav | | t2a\_async\_input | Entrada de texto longo assíncrona; txt, zip | A requisição deve conter exatamente um purpose e um arquivo. O limite do corpo de uma única requisição à plataforma é de 64 MiB; os limites da MiniMax de formato, duração e tamanho para cada finalidade continuam aplicáveis. ### 4.2 Consulta e download ```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 retorna os metadados do arquivo e download\_url; retrieve\_content retorna diretamente o arquivo binário. Upload, consulta e download não são cobrados. ## 5. Clonagem rápida de timbre Documentação oficial dos parâmetros: [Clonagem rápida de timbre](https://platform.minimaxi.com/docs/api-reference/voice-cloning-clone) ### 5.1 Chamar a API e campos ``` POST https://{api_domain}/v3/minimax/v1/voice_clone ``` | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | file\_id | integer | Sim | ID do arquivo obtido via upload com purpose=voice\_clone; áudio de 10 segundos a 5 minutos e no máximo 20 MB | | voice\_id | string | Sim | ID de timbre personalizado, com comprimento de 8–256, começando com uma letra, e que não pode ser duplicado com um ID existente | | clone\_prompt | object | Não | Áudio de exemplo; ao usar, prompt\_audio e prompt\_text são obrigatórios | | text | string | Não | Texto de prévia, com no máximo 1.000 caracteres | | model | string | Obrigatório condicionalmente | Obrigatório ao enviar text; use speech-2.8-hd ou speech-2.8-turbo | | text\_validation | string | Não | Texto esperado da amostra, com no máximo 200 caracteres | | accuracy | number | Não | Limite de similaridade de ASR, 0–1, padrão 0.7 | ### 5.2 Exemplo de chamada e resposta ```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" } } ``` Uma requisição bem-sucedida é cobrada como um timbre. Se a requisição gerar áudio de prévia, a plataforma não adiciona uma SKU extra de síntese de fala. A MiniMax informa oficialmente que um timbre clonado que não for formalmente usado em síntese de fala dentro de 7 dias poderá ser excluído. ## 6. Design de timbre Documentação oficial dos parâmetros: [Design de timbre](https://platform.minimaxi.com/docs/api-reference/voice-design-design) ### 6.1 Chamar a API e campos ``` POST https://{api_domain}/v3/minimax/v1/voice_design ``` | Campo | Tipo | Obrigatório | Descrição | | - | - | - | - | | prompt | string | Sim | Descrição do timbre desejado | | preview\_text | string | Sim | Texto de prévia, com no máximo 500 caracteres | | voice\_id | string | Não | ID de timbre personalizado; se não for enviado, é gerado pela MiniMax | | aigc\_watermark | boolean | Não | Se deve adicionar uma marca rítmica ao final do áudio de prévia; padrão false | ### 6.2 Exemplo de chamada e resposta ```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" } } ``` Uma requisição bem-sucedida é cobrada como um timbre; o áudio de prévia está incluído na cobrança desta API e não adiciona uma SKU extra de síntese de fala. ## 7. Erros comuns e observações | Fenômeno | Descrição e sugestão de tratamento | | - | - | | HTTP 200, mas base\_resp.status\_code!=0 | Erro de negócio da MiniMax; corrija a entrada conforme status\_msg e não trate como sucesso | | HTTP 400 | JSON, multipart, nome do modelo, parâmetros de consulta ou campos obrigatórios inválidos | | HTTP 401/403 | Verifique a chave de API da plataforma, o saldo e as permissões | | HTTP 404 | Arquivo, tarefa ou timbre privado inexistente, ou pertencente a outro usuário da plataforma | | HTTP 429 | Reduza a frequência de requisições/consultas e use backoff exponencial; consultas assíncronas não podem exceder 10 por segundo | | HTTP 5xx | Mantenha a resposta e o trace ID da plataforma e contate o suporte técnico; não repita sem controle requisições de criação não idempotentes | * Os campos oficiais são encaminhados como estão sempre que possível, mas este serviço expõe apenas os oito caminhos listados neste documento. * O limite do corpo de uma única requisição e de um único evento SSE é de 64 MiB. * Após a desconexão do cliente, o serviço pode continuar lendo o SSE já iniciado para concluir a apuração de uso. * Tarefas assíncronas devem obter o status pela API de consulta MiniMax deste documento, e não pela API genérica de resultados assíncronos da plataforma. * Baixe o arquivo em tempo hábil após receber a URL do arquivo ou um file ID de sucesso; a URL e os arquivos podem expirar. ## 8. Exemplo de chamada em Python Os exemplos a seguir demonstram criação assíncrona e polling. Em produção, defina timeout total, backoff exponencial e número máximo de tentativas de polling. ```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.