Tutorial
Tutorial da API minimax-music-1.5: curl e Python Requests
Nesta página
Requisitos de requisição do minimax-music-1.5
Antes de escrever a primeira linha de código, vale a pena entender exatamente o que uma chamada de geração de música contém. Diferente da conclusão de texto, uma requisição de música tem duas entradas criativas que desempenham papéis distintos, além de alguns controles que moldam a saída.
Em alto nível, uma requisição minimax-music-1.5 inclui:
- Descrição de estilo ou prompt — a direção musical: gênero, humor, instrumentação, sensação de andamento, características de produção.
- Letra — o texto realmente cantado quando a faixa tem vocais. Deixe vazio ou omita para requisições puramente instrumentais.
- Controle de estrutura — como a duração alvo da faixa gerada, que limita o comprimento da composição do modelo.
- Identificador do modelo —
minimax-music-1.5— faz o gateway rotear a tarefa para o backend correto.
O modelo mental a manter em mente: a entrada de estilo diz ao modelo como deve soar, a entrada de letra diz ao modelo o que é cantado. As duas não são intercambiáveis. Se você colocar uma descrição de gênero no campo de letra, obterá uma saída confusa; se deixar a letra vazia mas pedir uma faixa com vocais, o modelo terá que inventar. Decida em qual dos dois modos você está antes de começar.
Há mais dois pontos a internalizar antes de escrever código:
- A geração de música não é instantânea. Gerar uma faixa finalizada leva tempo real de computação, então a API é assíncrona por design. Você submete uma tarefa e depois busca o resultado. Qualquer tutorial que mostre apenas uma chamada bloqueante está escondendo o loop de polling de você.
- A saída é entregue por referência. Você recebe uma URL para o áudio gerado, não bytes brutos inline. O download ou streaming é feito separadamente.
Uma vez que você consiga explicar essas três coisas — a distinção entre estilo e letra, o ciclo de vida assíncrono e a saída baseada em URL — o corpo real da requisição se torna fácil de ler.
Configuração inicial na HiAPI
Você precisa de três coisas antes da primeira chamada: uma chave de API, o endereço base da interface e o hábito de não codificar a chave diretamente.
Chave de API
Crie a chave no console da sua conta HiAPI. Trate-a como uma senha: ela autentica cada requisição e está vinculada ao uso da sua conta. Nunca faça commit dela, nunca a cole em um gist público e nunca a empacote em bundles de mobile ou navegador.
Endereço base da interface
Todas as chamadas vão para o gateway HiAPI, que expõe o minimax-music-1.5 atrás de uma interface unificada única. Você não precisa de credenciais ou SDK separados por modelo — o nome do modelo no corpo da requisição seleciona o backend. Consulte a documentação de referência da API para obter a URL base exata e o caminho atual da requisição.
Mantenha a chave longe do código-fonte
O padrão que funciona desde scripts temporários até produção é a variável de ambiente:
export HIAPI_API_KEY="your-key-here"
Depois leia-a em tempo de execução. Em Python é os.environ["HIAPI_API_KEY"]; no shell é $HIAPI_API_KEY. Se usar um arquivo .env localmente, adicione-o ao .gitignore antes do primeiro commit — não depois. Para serviços implantados, injete a chave através do gerenciador de segredos da plataforma, não a inclua na imagem.
Faça uma verificação rápida antes de construir qualquer coisa: confirme que o processo que você está prestes a executar consegue ver a chave (execute echo $HIAPI_API_KEY no mesmo shell). A maioria dos relatos de "falha de autenticação" remonta a exportar a chave em um terminal e executar o script em outro.
Faça a primeira requisição funcional com curl
Comece com curl. Ele remove cada camada de abstração e mostra exatamente o que trafega na rede. A requisição abaixo gera uma faixa curta com vocais; ajuste os valores dos campos de acordo com sua própria intenção.
curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-music-1.5",
"prompt": "folk indie caloroso, violão acústico fingerstyle, bateria suave com escovação, vocal íntimo de proximidade",
"lyrics": "[verse]\nA luz da manhã se espalha pelo chão da cozinha\n[chorus]\nAinda estamos aqui, ainda estamos aqui",
"duration": 30
}'
Linha por linha:
-X POST— gerar é uma operação de criação, não de leitura.Authorization: Bearer $HIAPI_API_KEY— a chave da seção anterior, expandida pelo shell, então desde que você referencie a variável ela não aparecerá no seu histórico.Content-Type: application/json— o gateway espera JSON; omitir este cabeçalho é uma causa comum de respostas 4xx confusas.model— fixa a requisição no minimax-music-1.5.prompt— a descrição de estilo. Especifique instrumentação e humor em vez de usar apenas um adjetivo.lyrics— o texto cantado, usando marcadores leves de seção como[verse]e[chorus]para indicar estrutura. O escape\né a quebra de linha JSON.duration— limita o comprimento da faixa gerada em segundos.
O que volta é uma referência de tarefa, não áudio. Capture-a:
curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | tee job.json
Ler o corpo da requisição de um arquivo com -d @payload.json mantém seu histórico do shell limpo e torna a passagem para Python trivial — o arquivo é o corpo da requisição. Inspecione a resposta, anote o identificador de tarefa ou job e qualquer campo de status; você precisará desse identificador para buscar o resultado.
Porte a requisição para Python
A versão em Python deve parecer uma transcrição da chamada curl, não uma reescrita. Use requests, leia a chave da variável de ambiente e mantenha o corpo da requisição como um dicionário para facilitar a leitura.
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "minimax-music-1.5",
"prompt": "folk indie caloroso, violão acústico fingerstyle, bateria suave com escovação, vocal íntimo de proximidade",
"lyrics": "[verse]\nA luz da manhã se espalha pelo chão da cozinha\n[chorus]\nAinda estamos aqui, ainda estamos aqui",
"duration": 30,
}
response = requests.post(
f"{BASE_URL}/minimax-music-1.5",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))
Algumas notas de portabilidade para evitar surpresas:
- Use
json.dumpscomdata=, ou usejson=payload. Ambos funcionam;json=payloadfaz orequestsdefinir o tipo de conteúdo para você. Se você passar um dicionário diretamente paradata=sem serializar, o servidor receberá um corpo codificado como formulário e o rejeitará. - Sempre defina um
timeout. Sem isso, uma conexão travada fará seu processo travar indefinidamente. Lembre-se de que esse timeout cobre a submissão, não a geração — isso é o que a próxima seção aborda. - Chame
raise_for_status()antes de fazer o parse. Ele transforma um 4xx ou 5xx em uma exceção clara, em vez de um misteriosoKeyErrorquando você acessa um campo inexistente. - Mantenha o objeto de resposta. Ao depurar, imprimir
response.status_codeeresponse.textinforma muito mais do que o erro já parseado.
O resultado deste script é a mesma referência de tarefa que o curl produz. Tudo após a submissão — polling, retentativas, download — é idêntico em qualquer linguagem, e é exatamente por isso que merece uma seção própria.
Lide com o ciclo de vida de tarefas assíncronas
O erro mais comum na geração de música é tratá-la como uma conclusão de chat: enviar, esperar, ler a faixa. A chamada de submissão retorna rapidamente, mas o áudio ainda não existe. Seu código precisa fechar o ciclo.
Os três estados
Cada tarefa passa por uma pequena máquina de estados:
- Submetida (Submitted) — você obteve o identificador de tarefa, o trabalho está na fila ou em execução.
- Concluída (Finished) — o áudio está pronto, a resposta traz uma URL apontando para ele.
- Falhou (Failed) — a geração foi abortada; a resposta explica o motivo.
Seu loop de polling deve distinguir os três estados. O status submitted significa continuar esperando, não tentar novamente.
Faça polling, não martele
Um loop ingênuo que dispara verificações de status o mais rápido que a CPU permitir consumirá limites de taxa e não lhe dirá nada novo — renderizar uma faixa leva dezenas de segundos, então centenas de verificações por minuto são desperdício puro. Adicione backoff:
import time
def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"{base_url}/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "finished":
return data
if status == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} not finished after {max_wait}s")
Consulte a documentação de referência da API para obter o caminho de polling exato e as strings de status — trate os nomes acima como ilustrativos e alinhe-os com os valores da documentação.
Tente novamente o objeto correto
As retentativas pertencem a dois níveis distintos, e confundi-los leva a trabalho duplicado. Retentativas de transporte — a chamada HTTP em si falha por um 5xx ou reset de conexão — podem ser repetidas com segurança em requisições de polling. Retentativas de geração são novas submissões que custam outra renderização, então só faça isso quando a tarefa relatar explicitamente falha, e limite o número de vezes. Nunca repita uma submissão só porque o polling está lento.
Por fim, persista o identificador de tarefa no momento em que o receber. Se seu processo travar entre a submissão e a conclusão, esse identificador é a única forma de recuperar a faixa concluída sem pagar por uma nova geração.
Ajuste as entradas de letra, estilo e duração
Obter uma faixa utilizável do minimax-music-1.5 depende principalmente de escrever esses dois campos de texto com intenção. Alguns hábitos determinam se a saída é genérica ou algo que você realmente publicaria.
Escreva o prompt de estilo como um briefing de produtor
Uma única palavra de gênero dá liberdade demais ao modelo. Empilhe dimensões concretas:
- Gênero e época — "trip hop do final dos anos 90" supera "eletrônico".
- Instrumentação — nomeie os instrumentos principais e a seção rítmica.
- Humor e energia — "melancólico mas impulsionado" cria uma tensão que um único adjetivo não expressa.
- Características de produção — "lo-fi, saturação de fita, estéreo amplo" orienta a mixagem.
Mantenha em uma ou duas frases. Prompts em formato de parágrafo longo tendem a diluir em vez de refinar.
Organize a estrutura da letra com marcadores
Marcadores leves de seção — [verse], [chorus], [bridge] — dão ao modelo um roteiro e geralmente produzem uma estrutura de música mais clara do que um bloco de texto sem marcação. Mantenha cada linha curta o suficiente para ser cantada; uma linha de doze palavras raramente se encaixa em uma melodia. Para faixas instrumentais, omita completamente lyrics em vez de enviar uma string vazia contendo texto de estilo.
Faça a duração corresponder ao material
A duração limita a composição. Uma duração curta com uma letra completa de verse-chorus-verse força compressão e soa apressada; uma duração longa com duas linhas de letra convida à repetição. Decida primeiro a forma da música e depois defina a duração que se encaixa nela. Se precisar de uma peça mais longa, expanda a letra em vez de esticar a duração e torcer para que funcione.
Itere com pequenas mudanças
Quando uma faixa está quase certa mas não exatamente, mude apenas uma entrada por vez — a instrumentação no prompt, ou a palavra de andamento, ou aquela linha de letra que não funcionou. Mudar tudo de uma vez impede que você saiba qual campo trouxe a melhoria. Guarde seu melhor corpo de requisição em um arquivo e ramifique a partir dele.
Solucione erros comuns
A maioria das falhas se enquadra em algumas categorias reconhecíveis. Combine o sintoma, aplique a correção e siga em frente.
Falhas de autenticação
Sintoma: 401 ou 403, com mensagem relacionada a credenciais.
- Confirme que o cabeçalho é
Authorization: Bearer <key>— a palavraBearere o espaço são obrigatórios. - Verifique se a variável de ambiente está realmente definida no processo que faz a requisição. Uma chave exportada em um shell não chega a um cron job ou contêiner Docker.
- Verifique espaços em branco extras ou quebras de linha copiadas junto com a chave.
Corpo de requisição malformado
Sintoma: 400, com mensagem de validação.
- Envie
Content-Type: application/json. A falta desse cabeçalho faz o servidor interpretar mal um corpo de requisição perfeitamente correto. - Se usar
requests, passejson=payloadoudata=json.dumps(payload). Passar um dicionário bruto paradata=faz com que ele seja codificado como formulário. - Valide nomes e tipos de campos com a documentação de referência da API:
modeldeve ser exatamenteminimax-music-1.5,durationé um inteiro, e quebras de linha na letra precisam ser corretamente escapadas como\nem JSON. - Em caso de dúvida, use
curl -d @payload.jsonpara isolar se o corpo da requisição em si é válido antes de envolver qualquer Python.
Timeouts e erros de conexão
Sintoma: a requisição trava ou lança um erro de conexão.
- Defina um
timeoutexplícito para cada chamada. O timeout de submissão deve ser generoso o suficiente para cobrir a latência da fila, mas não é o tempo de renderização. - Não defina seu timeout de polling igual ao
max_waitgeral; uma única verificação de status lenta não deve abortar uma tarefa ainda em execução. - Se a submissão der timeout repetidamente enquanto o polling tiver sucesso, seu corpo de requisição pode estar muito grande — reduza a letra.
Erros de polling
Sintoma: você faz polling continuamente e nunca vê finished, ou está consultando o recurso errado.
- Confirme que está usando o identificador de tarefa da resposta de submissão, não um ID de requisição ou cabeçalho de correlação.
- Trate
submitted/runningcomo "continue esperando" em vez de "reenvie a submissão". Reenviar gera uma segunda faixa. - Adicione backoff. Polling agressivo atrai limites de taxa, que parecem falhas mas são autoinfligidos.
- Se a tarefa relatar
failed, leia a mensagem antes de reenviar — marcadores de letra inválidos ou duração fora do intervalo falharão da mesma forma toda vez.
Quando ficar travado, volte à chamada curl bruta com -v para ver a linha de status e os cabeçalhos reais. Esse passo elimina a maioria das ambiguidades mais rápido do que qualquer quantidade de depuração em Python.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio