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

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=
Upload de arquivo	POST /v3/minimax/v1/files/upload
Consultar arquivo	GET /v3/minimax/v1/files/retrieve?file_id=
Baixar arquivo	GET /v3/minimax/v1/files/retrieve_content?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 <YOUR_API_KEY>
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

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

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 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

{
  "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, Consultar tarefa assíncrona

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

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"
  }
}

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

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

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.

{
  "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, Recuperação de arquivo, Download de arquivo

4.1 Upload de arquivo

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 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

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 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

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

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"
  }
}

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

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

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"
  }
}

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.

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 modificação em 21 de outubro de 2026

Noções básicas da API

Modelos de linguagem

Imagens

Vídeo

Áudio

MiniMax Speech

1. Visão geral

1.1 Endereços das APIs

1.2 Autenticação

1.3 Respostas e acesso a recursos

2. Síntese de fala síncrona

2.1 Chamar a API

2.2 Exemplo de chamada

2.3 Descrição da resposta

2.4 Cobrança

3. Síntese de fala assíncrona para textos longos

3.1 Criar tarefa

3.2 Exemplo de criação

3.3 Consultar tarefa

4. Gerenciamento de arquivos

4.1 Upload de arquivo

4.2 Consulta e download

5. Clonagem rápida de timbre

5.1 Chamar a API e campos

5.2 Exemplo de chamada e resposta

6. Design de timbre

6.1 Chamar a API e campos

6.2 Exemplo de chamada e resposta

7. Erros comuns e observações

8. Exemplo de chamada em Python

​1. Visão geral

​1.1 Endereços das APIs

​1.2 Autenticação

​1.3 Respostas e acesso a recursos

​2. Síntese de fala síncrona

​2.1 Chamar a API

​2.2 Exemplo de chamada

​2.3 Descrição da resposta

​2.4 Cobrança

​3. Síntese de fala assíncrona para textos longos

​3.1 Criar tarefa

​3.2 Exemplo de criação

​3.3 Consultar tarefa

​4. Gerenciamento de arquivos

​4.1 Upload de arquivo

​4.2 Consulta e download

​5. Clonagem rápida de timbre

​5.1 Chamar a API e campos

​5.2 Exemplo de chamada e resposta

​6. Design de timbre

​6.1 Chamar a API e campos

​6.2 Exemplo de chamada e resposta

​7. Erros comuns e observações

​8. Exemplo de chamada em Python

1. Visão geral

1.1 Endereços das APIs

1.2 Autenticação

1.3 Respostas e acesso a recursos

2. Síntese de fala síncrona

2.1 Chamar a API

2.2 Exemplo de chamada

2.3 Descrição da resposta

2.4 Cobrança

3. Síntese de fala assíncrona para textos longos

3.1 Criar tarefa

3.2 Exemplo de criação

3.3 Consultar tarefa

4. Gerenciamento de arquivos

4.1 Upload de arquivo

4.2 Consulta e download

5. Clonagem rápida de timbre

5.1 Chamar a API e campos

5.2 Exemplo de chamada e resposta

6. Design de timbre

6.1 Chamar a API e campos

6.2 Exemplo de chamada e resposta

7. Erros comuns e observações

8. Exemplo de chamada em Python