API minimax-music-3: guia com curl e Python

Gerar uma faixa no minimax-music-3 pela hiapi exige apenas uma chamada POST /v1/tasks seguida de polling — exatamente o mesmo padrão de tarefas assíncronas usado por todos os modelos da plataforma. Este guia registra requisições e respostas reais (criação da tarefa, polling e URL final do áudio), então o código abaixo pode ser copiado e executado, não é apenas ilustrativo.

O que você precisa

1. Uma chave de API da hiapi — crie no console. Ela é enviada como token Bearer em cada requisição.
2. É só isso. Diferente de modelos de vídeo a partir de imagem ou imagem a partir de imagem, o minimax-music-3 não aceita arquivos nem URLs de entrada — ele gera apenas a partir de texto.

Requisição mínima funcional (curl)

Criar a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

Resposta:

{"code":200,"data":{"taskId":"tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55"},"message":"success"}

Faça polling da tarefa até a conclusão:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

Enquanto a tarefa está em execução, status passa por handling → archiving e finalmente se torna success (ou failed). Nos testes, uma faixa levou cerca de dois minutos e meio do envio até success. A resposta após a conclusão é assim:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url é o arquivo WAV. Observe expireAt — antes de construir qualquer funcionalidade que dependa da validade de longo prazo dessa URL, leia as notas sobre armazenamento abaixo.

O mesmo fluxo em Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

Parâmetros que o minimax-music-3 realmente valida

O schema de entrada é estrito — enviar um campo não listado faz a API rejeitar a requisição inteira antes mesmo de ela entrar na fila:

• prompt (string, obrigatório) — estilo, clima, instrumentação. É isso que efetivamente define a forma da faixa.
• lyrics (string, obrigatório) — sempre obrigatório, mesmo para faixas puramente instrumentais. Passe "[Instrumental]" como placeholder; para faixas com vocais, use tags de seção como [Verse] / [Chorus].
• callback (objeto, opcional) — {"url": "...", "when": "final"}. O único valor aceito para when é "final"; qualquer outro valor retorna 400 com a mensagem invalid callback.when: only 'final' is supported.

Enviar qualquer coisa além dessas três chaves de nível superior — como sample_rate, duration ou um erro de digitação — resulta em:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

Considerações para produção

• Duas formas distintas de erro. Erros de validação (campo ausente, valor de enum inválido, chave desconhecida) retornam no nível superior {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Erros de autenticação/permissão retornam {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — um objeto error aninhado, HTTP 401. Verifique ambos os formatos no seu tratamento de erros; um código que só verifica resp["code"] vai perder o caso 401.
• permission_denied indica um problema com a chave, não com a requisição. Se prompt/lyrics estão presentes e com tipos corretos, mas você ainda recebe 401 permission_denied, então a própria chave de API não tem esse modelo habilitado — verifique isso no console em vez de reler seu JSON repetidamente.
• O armazenamento dos arquivos de saída é temporário. storage: "temp" e um timestamp Unix expireAt em cada saída — no exemplo capturado, cerca de 7 dias após a criação. Assim que a tarefa for concluída com sucesso, baixe o arquivo imediatamente ou envie-o para o seu próprio armazenamento; não guarde a URL de temp.hiapi.ai como se fosse um link permanente.
• Para qualquer tarefa em lote, use callback. Fazer polling de uma faixa tudo bem; fazer polling de cinquenta significa cinquenta idas e voltas repetidas. Configure callback.url e when: "final" para que a hiapi envie o resultado uma única vez quando a tarefa realmente terminar.
• Tente novamente antes de obter o taskId, não depois. Repetir a POST /v1/tasks inicial em caso de erro de rede ou 5xx é seguro — nada foi criado ainda. Depois que você tem um taskId, reenviar o mesmo prompt cria outra faixa não relacionada; nesse caso, faça polling ou aguarde o callback.

Conteúdo relacionado

• Página do modelo minimax-music-3 — preços atuais e área de experimentação online.
• Preços da hiapi — tarifas de todos os modelos do catálogo.
• Documentação da hiapi — referência completa da API, além deste modelo específico.

Perguntas frequentes

Faixas puramente instrumentais precisam de letras? Sim — independentemente de você querer vocais ou não, lyrics é um campo obrigatório. Passe "[Instrumental]" e o modelo gerará uma faixa sem vocais.

É possível evitar completamente o polling? Sim, configure callback: {"url": "https://your-endpoint", "when": "final"} ao criar a tarefa. Quando a tarefa atingir um estado terminal, a hiapi fará um POST no seu URL com o mesmo payload de GET /v1/tasks/:id. No momento, "final" é o único valor aceito para when.

Por que recebo "additional properties not allowed"? O schema de entrada do minimax-music-3 aceita dentro de input apenas prompt e lyrics (além do callback no nível superior). Qualquer outro nome de campo — mesmo que funcione em outros modelos da hiapi — será rejeitado antes que a requisição seja executada.

Por que uma chave que funciona em outros modelos retorna 401 neste modelo? O acesso aos modelos é concedido por chave. Um 401 com error_code: "permission_denied" significa que essa chave específica ainda não recebeu permissão para o minimax-music-3 — habilite-a no console; não é um bug no seu corpo de requisição.

Quanto tempo posso esperar antes de baixar o arquivo de saída? Não espere — output[0].url é um link temporário (na prática, expireAt fica cerca de uma semana à frente). Trate-o como uma entrega única: baixe ou reenvie imediatamente após o sucesso da tarefa.