Como usar mureka-9.5/instrumental pela API HiAPI: guia com curl e Python

O que mureka-9.5/instrumental faz na HiAPI

mureka-9.5/instrumental é um endpoint de geração de música a partir de texto na HiAPI, ajustado especificamente para saídas puramente instrumentais — música de fundo, loops, camadas de base e trilhas sonoras. Você descreve a faixa com um prompt, envia uma única tarefa, e a HiAPI retorna um recurso de áudio concluído que você pode baixar e usar em jogos, edições de vídeo, podcasts ou demonstrações de produto.

A palavra instrumental é a chave. O endpoint é voltado para músicas sem performance de vocal principal, o que o torna adequado para cenas em que a narração ou o diálogo precisam permanecer claros e compreensíveis. Se você precisa de faixas cantadas com letra, esse é outro problema; se você precisa de uma camada limpa de música de fundo sob uma dublagem, esta é a ferramenta correta.

Escolha este endpoint quando:

• Você quer gerar música de fundo (BGM), em vez de retirá-la de uma biblioteca musical.
• Você precisa gerar rapidamente, de forma programática, muitas variantes, em vez de uma composição sob encomenda única.
• Seu pipeline já usa HTTP e você quer tratar a música como qualquer outra etapa de geração de recurso.
• Você se importa com um formato de requisição previsível: envio, polling, download.

Como em outros endpoints de geração de música, o trabalho é assíncrono. Após o envio, é retornada uma tarefa, e você precisa acompanhá-la até o áudio ser gerado. Projete seu código em torno disso desde o início, e o restante da integração será rotina.

Onde ele se encaixa no produto

O usuário típico é um pipeline de conteúdo que precisa de faixas sob demanda: um renderizador de vídeo que quer uma camada de música sob cada clipe, um jogo que quer um loop ambiente, ou uma ferramenta de prototipagem que permite ao usuário digitar um clima e ouvir o resultado. Como o endpoint é orientado por texto, você pode modelar prompts a partir de metadados que já tem — gênero, senso rítmico, clima e duração esperada — e gerar no momento da renderização.

Trate cada requisição como uma tarefa de geração com seu próprio ciclo de vida. Essa estrutura mantém sua lógica de repetição, registro e contabilização de custos razoáveis.

Preparação antes de enviar a requisição

Antes da primeira chamada bem-sucedida, algumas condições precisam ser atendidas. Nenhuma é complexa, mas deixar uma de fora é a causa mais comum de falha na primeira requisição.

Credenciais

Você precisa de uma chave de API da HiAPI. Trate-a como segredo: carregue-a de uma variável de ambiente como HIAPI_API_KEY, nunca a codifique diretamente nos scripts que você envia, e rotacione-a se vazar. A chave é enviada como token bearer no cabeçalho Authorization.

export HIAPI_API_KEY="your_api_key_here"

Endpoint e transporte

Você chama o modelo mureka-9.5/instrumental pela API unificada da HiAPI. A URL base é o host da API HiAPI; o identificador do modelo fica no payload da requisição ou no caminho, conforme a convenção documentada pela HiAPI para esse endpoint. Use HTTPS, envie Content-Type: application/json e envie um corpo JSON.

Não adivinhe nomes de parâmetros. A HiAPI documenta os campos aceitos por esse modelo; qualquer coisa fora desse conjunto é, na melhor das hipóteses, ignorada, e na pior, rejeitada. Se o campo que você quer não está documentado, ele não faz parte do contrato — construa com base no que existe.

O que preparar

• Um prompt que descreva a música: gênero, instrumentação, clima, senso rítmico e uso pretendido.
• As opções de duração ou variantes documentadas e expostas publicamente pelo modelo.
• Um local para armazenar o identificador da tarefa e, mais tarde, a URL de download.
• Acesso de rede do local onde o código roda até o host da HiAPI.

Uma observação sobre tempo

A geração não é instantânea. Configure o timeout do cliente com folga e espere precisar fazer polling. A mentalidade síncrona — enviar a requisição e bloquear até o áudio voltar na mesma resposta — leva a código instável.

Uma requisição curl funcional

Comece com curl. Ele remove todas as camadas entre você e a conversa HTTP, então, se houver um problema, você o vê imediatamente.

A chamada

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "warm lo-fi hip hop instrumental, mellow electric piano, soft vinyl crackle, relaxed 80 bpm, no vocals"
    }
  }'

Defina as duas variáveis de ambiente primeiro, assim nenhuma informação sensível fica em texto claro no histórico do shell além do conteúdo que você escolher:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # 使用该端点有文档记录的路径
export HIAPI_API_KEY="your_api_key_here"

O que cada parte faz

• -X POST — o envio é uma operação de criação.
• -H "Authorization: Bearer ..." — autentica a chamada com sua conta.
• -H "Content-Type: application/json" — informa ao servidor que o corpo é JSON; se omitir, muitos servidores rejeitam o corpo diretamente.
• -d '{...}' — o payload JSON. O campo model especifica o endpoint; o objeto input carrega seu prompt e outros campos documentados.
• -sS — modo silencioso para progresso, mas ainda mostra erros. Útil em scripts.

Lendo a resposta

A resposta é JSON. Você procura um identificador de tarefa ou job e um campo de status. Formate a saída para inspecionar:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

Guarde o identificador. Ele é o handle para cada verificação de status posterior. Não analise o corpo inteiro da resposta dentro da sua aplicação; extraia o ID da tarefa e o status, e armazene a resposta bruta para depuração.

Se você receber um status fora de 2xx, leia o corpo — a HiAPI retorna mensagens de erro estruturadas, normalmente apontando o campo problemático.

A mesma requisição em Python

A versão em Python corresponde exatamente à chamada curl: mesmos cabeçalhos, mesmo corpo JSON. Use requests pela simplicidade, ou a biblioteca padrão se quiser zero dependências.

Usando requests

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "warm lo-fi hip hop instrumental, mellow electric piano, "
            "soft vinyl crackle, relaxed 80 bpm, no vocals"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # use o nome de campo documentado
print("submitted:", job_id, data.get("status"))

Usando a biblioteca padrão

Se você não pode adicionar dependências:

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

Hábitos práticos

• Use timeout=30 apenas no envio. O polling precisa do próprio loop e do próprio timeout.
• Chame raise_for_status() antes de analisar. Um corpo de resposta de erro não é uma tarefa.
• Envolva a extração do ID da tarefa em um pequeno helper, assim uma mudança de nome de campo exige correção em uma linha.
• Nunca registre a chave de API; registre o ID da tarefa e o status.
• Mantenha o payload como um dicionário no código, serialize uma vez, para que os testes possam verificar seu valor.

Lidando com tarefas assíncronas e polling

O envio é o primeiro passo. A geração acontece no lado do servidor e termina mais tarde, então você faz polling do endpoint de status até a tarefa relatar um estado terminal.

Formato do loop

1. Envie a tarefa e capture o ID.
2. Durma brevemente.
3. Consulte o status desse ID.
4. Se o status for na fila ou em processamento, aguarde com backoff e repita.
5. Se o status for de sucesso, leia a saída.
6. Se o status for de falha, registre o erro e pare — não repita às cegas.

Uma implementação confiável

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # jitter
        delay = min(delay * 1.5, max_delay)          # exponential backoff

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

Por que cada detalhe importa

• Jitter evita tentativas sincronizadas quando várias tarefas rodam em paralelo.
• Backoff evita martelar o endpoint de status enquanto a faixa é renderizada.
• Deadline transforma uma espera infinita em uma exceção limpa que o pipeline consegue tratar.
• Verificação de estado terminal deve corresponder às strings de status documentadas pela HiAPI. Confirme-as na referência da API em vez de confiar em suposições.
• Repetições devem cobrir erros de rede transitórios (timeout, 5xx), e não tarefas que já falharam por erro de validação.

Dicas operacionais

Persista o job_id antes de começar o polling. Se seu processo morrer, você pode retomar o polling em vez de pagar por uma segunda geração. Registre as transições de estado com data e hora, para ver onde o tempo é gasto. Se você executa muitas tarefas, faça polling paralelo de poucas tarefas via fila, em vez de bloquear uma thread de requisição em cada tarefa.

Obtendo a saída instrumental e baixando

O modo instrumental é expresso pela sua requisição, e o endpoint é dedicado a esse tipo de saída. Na prática, a redação do prompt reforça isso: nomeie instrumentos, descreva o clima e declare a ausência de vocais. Prompts que pedem linhas vocais entram em conflito com o propósito do endpoint.

Onde o áudio aparece

Quando a tarefa atinge o estado de sucesso, a resposta de status traz o resultado. Espere que o áudio seja entregue como uma URL obtida separadamente, não como base64 no JSON de status. Leia a resposta e extraia a URL de download do campo de saída documentado.

result = wait_for_job(job_id, status_url, headers)
# 前几次仔细检查结果，然后固定该字段。
audio_url = result["output"]["audio_url"]   # 在 API 参考中确认字段名

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

Hábitos de download

• Grave em disco por streaming. Arquivos de música são grandes; carregá-los totalmente na memória é um estresse evitável.
• Verifique o tipo de conteúdo. Armazene o arquivo com a extensão sugerida pela resposta, não com uma extensão fixa no código.
• Trate a URL como temporária. Baixe logo, ou persista a URL apenas se a documentação disser que ela é estável. Copie os bytes para o seu próprio armazenamento para persistência.
• Baixe apenas uma vez. Baixar em um loop de repetição sem marcador de conclusão cria facilmente arquivos parciais. Grave com um nome temporário e renomeie após sucesso.
• Registre a procedência. Armazene o ID da tarefa e o prompt junto com o arquivo. Quando precisar de uma variante depois, você tem a entrada exata.

Pontos comuns de falha e correções

A maioria dos problemas de primeira integração cai em uma lista curta. Segue a lista de verificação.

401 / 403 — autenticação. O cabeçalho está errado, a chave está ausente ou a variável de ambiente resolveu para string vazia. Verifique se a chave está definida no mesmo shell ou processo em que o código roda, e se o cabeçalho lê exatamente Authorization: Bearer <key>.

400 — payload malformado. Falta model, há um erro de digitação em mureka-9.5/instrumental, JSON inválido, ou um campo que o endpoint não aceita. Envie o corpo primeiro com curl para isolar o payload do código. Valide o JSON antes de enviar; vírgulas finais são o problema clássico.

415 ou erro de corpo vazio — tipo de conteúdo. O Content-Type: application/json precisa estar presente. Alguns clientes HTTP o definem automaticamente quando você passa json=, mas não todos.

Timeout de polling. Seu deadline é curto demais, seu backoff é agressivo demais, ou a tarefa realmente falhou e você a classificou como ainda em execução. Verifique as strings de status exatas na documentação e imprima cada transição de estado ao depurar.

URL de download ausente. Você leu o campo errado, ou leu a resposta antes de a tarefa atingir o estado terminal de sucesso. Registre um payload de sucesso completo, confirme o caminho da URL de áudio e então fixe-o.

Geração duplicada. Seu poller travou e algo reenviou a tarefa. Persista o ID da tarefa antes do polling, e verifique tarefas existentes antes de enviar uma nova.

Limite de taxa. Faça backoff com jitter em respostas 429 e enfileire o trabalho, em vez de disparar de muitas threads ao mesmo tempo.

Trate-os nessa ordem — autenticação, payload, tipo de conteúdo, polling, saída — e você normalmente encontra a causa de primeira. Assim que a chamada curl e a versão gêmea em Python tiverem sucesso de ponta a ponta, o endpoint estará fazendo o que você pediu: transformando prompts em faixas instrumentais e entregando a você uma URL de download.