Como usar a MiniMax Music API (minimax-music-1.5): curl, Python e uma requisição executável

Este guia mostra como usar o minimax-music-1.5 na API de tarefas unificada do hiapi para gerar uma música completa a partir de um prompt de estilo e uma letra — com vocais, instrumentos e estrutura de arranjo. Tudo abaixo foi verificado contra o endpoint real e pode ser copiado, colado e executado diretamente.

O que você vai construir e o que precisa preparar

Objetivo: enviar uma descrição textual de estilo musical e sua letra, e receber uma faixa de áudio para download.

Você só precisa de uma coisa: uma chave de API do hiapi. Obtenha-a no seu painel — ela começa com sk-. Todos os exemplos abaixo presumem que ela está armazenada em uma variável de ambiente:

export HIAPI_KEY="sk-your-key-here"

A geração de música no hiapi usa a mesma interface de tarefas assíncronas de todos os outros modelos: POST /v1/tasks cria a tarefa, e então você consulta GET /v1/tasks/<taskId> em polling ou recebe um callback quando a tarefa terminar.

Schema de entrada (verificado)

O minimax-music-1.5 aceita os seguintes campos em input — qualquer outro campo é rejeitado com 400:

Campo	Obrigatório	Tipo	Restrições
prompt	Sim	string	10–300 caracteres. Descreva o gênero, o clima, a instrumentação e o estilo vocal.
lyrics	Sim	string	10–600 caracteres. A letra a ser cantada; suporta tags de seção como [Verse] e [Chorus].
sample_rate	Não	integer	Um de 16000, 24000, 32000, 44100.
bitrate	Não	integer	Um de 32000, 64000, 128000, 256000.

Há dois pontos de atenção:

1. Ambos prompt e lyrics são obrigatórios. O prompt controla como soa; o lyrics controla o que é cantado. Faltar qualquer um retorna invalid input: ... missing required field.
2. O schema é estrito. Campos que você talvez espere de outras APIs de música — duration, seed, format, instrumental — não são aceitos. Enviá-los retorna additional properties ... not allowed.

Exemplo mínimo executável: curl

Crie a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "Uplifting acoustic pop, warm female vocals, gentle guitar and light percussion",
      "lyrics": "[Verse]\nMorning light on a quiet street\nCoffee steam and a steady beat\n[Chorus]\nWe keep on going, we find our way\nOne small step at a time, every day",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

A criação bem-sucedida retorna um id de tarefa:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Em seguida, faça polling até a tarefa atingir um estado terminal:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

Enquanto a tarefa está em execução, você verá um status não terminal; ao concluir, o status muda para success e a URL do áudio aparece em output:

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

Baixe o arquivo o quanto antes — as URLs de saída têm validade limitada e devem ser tratadas como uma janela de retirada, não como armazenamento permanente:

curl -o track.mp3 "https://.../track.mp3"

Script Python completo: enviar, fazer polling, baixar

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("Uplifting acoustic pop, warm female vocals, "
                       "gentle guitar and light percussion"),
            "lyrics": ("[Verse]\nMorning light on a quiet street\n"
                       "Coffee steam and a steady beat\n"
                       "[Chorus]\nWe keep on going, we find our way\n"
                       "One small step at a time, every day"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

Execute-o com python3 make_song.py. O script envia a tarefa, faz polling a cada 5 segundos e salva a faixa concluída localmente.

Padrões para produção

Use callback em vez de polling

Para qualquer uso além de um script rápido, registre um callback para que o hiapi envie o resultado quando a tarefa atingir um estado terminal. Adicione um objeto callback de nível superior (no mesmo nível de model, não dentro de input):

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

Apenas "when": "final" é suportado — você recebe um único POST quando a tarefa tem sucesso ou falha, e não eventos incrementais de progresso. O polling é adequado para desenvolvimento e tarefas únicas; quando você vai gerar muitas faixas ou está executando atrás de uma fila, o callback é melhor, pois você não precisa manter um loop aberto nem correr o risco de atingir limites de taxa por polling de alta frequência. Se o callback nunca chegar, siga a lista de verificação em Por que seu callback de tarefa do hiapi não dispara.

Idempotência e retentativas

A criação de tarefa em si não é idempotente: repetir um POST /v1/tasks que deu timeout pode criar duas tarefas (e gerar duas cobranças). Persista o taskId imediatamente após a chamada de criação retornar e, ao reiniciar, retome consultando esse id em vez de reenviar às cegas. Se a tarefa parecer travada, não a mate e recrie imediatamente — consulte Tarefas do hiapi /v1/tasks travadas ou expirando para saber como distinguir uma tarefa lenta de uma tarefa morta.

Tratamento de erros

Dois tipos de falha se comportam de modo diferente:

• Erros de nível de requisição são retornados de forma síncrona. Uma chave inválida ou não autorizada retorna um erro permission_denied ("This API key cannot use the selected model..."), acompanhado de um request_id que você pode citar ao suporte. Violações de schema retornam 400 INVALID_REQUEST com uma mensagem precisa, por exemplo prompt: minLength: got 1, want 10.
• Falhas de nível de tarefa aparecem no resultado do polling/callback como status: "fail", com error.code e error.message — a chamada de criação teve sucesso, mas a geração não. Essas são as falhas que devem entrar na lógica de retentativa.

Valide os comprimentos no cliente antes de enviar: prompt tem no máximo 300 caracteres e lyrics no máximo 600 caracteres; a API rejeita entradas longas demais em vez de truncá-las.

Preços e limites

O MiniMax Music 1.5 é cobrado por faixa gerada, com preço baseado em uso — consulte as tarifas atuais na página de preços do hiapi e na página do modelo minimax-music-1.5, onde você também pode experimentar o modelo no playground antes de escrever qualquer código.

Perguntas frequentes

Quais campos de entrada o minimax-music-1.5 aceita?

Exatamente quatro: prompt (obrigatório, 10–300 caracteres), lyrics (obrigatório, 10–600 caracteres), sample_rate (opcional, 16000/24000/32000/44100) e bitrate (opcional, 32000/64000/128000/256000). Qualquer outro campo é rejeitado com additional properties not allowed.

É possível controlar a estrutura da música?

Sim — use tags de seção como [Verse] e [Chorus] em lyrics para organizar a estrutura. O modelo usa essas tags para moldar o arranjo. A string completa da letra (incluindo as tags) deve permanecer dentro do limite de 600 caracteres.

É possível gerar música puramente instrumental?

O schema de entrada não tem uma opção de instrumental. O endpoint é orientado por letra, então descreva no prompt a instrumentação e o clima que você deseja; para casos de uso puramente instrumentais, consulte a página do modelo para ver a lista atual de capacidades.

Como obter o arquivo de áudio?

Quando o status da tarefa é success, data.output[0].url contém o link de download. Obtenha-o imediatamente e armazene os bytes por conta própria — as URLs de saída expiram.

Devo usar polling ou callback?

Use polling para desenvolvimento e tarefas únicas (intervalo de 5 segundos é suficiente). Em produção, use callback com when: "final" para evitar manter conexões abertas — especialmente ao gerar faixas em lote.

Por que recebo permission_denied?

Sua chave é inválida ou não tem acesso a esse modelo. Valide a chave no painel e certifique-se de enviá-la como Authorization: Bearer sk-....