Como chamar a API mirelo-sfx-2.0 via HiAPI: curl, Python e polling assíncrono

Funcionalidades e cenários de aplicação do mirelo-sfx-2.0

O mirelo-sfx-2.0 é um modelo de texto para efeitos sonoros disponível via HiAPI. Você fornece uma descrição em linguagem natural — por exemplo, "uma porta de madeira pesada se abrindo lentamente com um rangido" ou "uma moeda caindo sobre uma mesa de mármore" — e ele gera um clipe de áudio curto que corresponde ao prompt.

Este é o endpoint a usar quando você precisa de design de som gerado sob demanda, em vez de licenciar amostras de uma biblioteca:

• Prototipagem de jogos e aplicativos: gerar efeitos sonoros provisórios ou finais para interações, eventos de UI e loops ambientes.
• Pós-produção de vídeo e podcast: preencher lacunas com áudio no estilo foley sem precisar agendar um estúdio de gravação.
• Pipelines generativos: obter prompts de roteiros, storyboards ou entrada do usuário e anexar o WAV gerado à saída.

O modelo tem melhor desempenho quando a descrição sonora é clara e a duração é curta. Se você precisa de música, fala ou áudio longo, isso pertence a outra família de modelos — o mirelo-sfx-2.0 é focado em efeitos sonoros discretos.

Como a geração é assíncrona, planeje a integração com base em tarefas, em vez de chamadas HTTP bloqueantes. O restante deste tutorial construirá essa integração, desde a requisição bruta com curl até um cliente Python que faz polling até obter o WAV finalizado.

Pré-requisitos e configuração de autenticação

Antes da primeira chamada, verifique se você tem:

• Uma conta HiAPI e uma chave de API. Você pode criar e gerenciar chaves no console da HiAPI. Trate a chave como uma senha: carregue-a de variáveis de ambiente ou de um gerenciador de segredos, e nunca a envie para um repositório de código.
• Uma ferramenta para enviar requisições HTTP. O curl basta para este passo a passo; os exemplos de código usam Python 3.8+.
• Um cliente HTTP em Python. Os exemplos usam requests por simplicidade, mas qualquer cliente capaz de enviar JSON e cabeçalhos serve.

A HiAPI usa uma única URL base e um único método de autenticação para todos os modelos, então as convenções que você aprende aqui valem para outros endpoints também:

export HIAPI_API_KEY="your-api-key-here"

Cada requisição envia a chave no cabeçalho Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

O identificador do modelo é passado no corpo da requisição via "model": "mirelo-sfx-2.0". Não é necessário instalar um SDK separado — desde que seu cliente HTTP consiga acessar a URL base da HiAPI, você pode chamar o modelo.

Uma dica prática: guarde a URL base em uma variável de configuração, em vez de codificá-la diretamente em cada arquivo. Quando você migrar de um script local para um serviço de staging ou produção, vai querer alterá-la em apenas um lugar.

Análise passo a passo da requisição curl

A requisição de geração é um POST HTTP autenticado enviado ao endpoint de criação de tarefas da HiAPI. Segue a chamada completa:

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "heavy wooden door creaking open slowly, old house ambience"
    }
  }'

Desmontando parte por parte:

• -X POST — a criação de tarefas é uma operação de escrita. Usar GET nesse caminho não inicia uma tarefa.
• URL — o endpoint aceita novas tarefas de geração. A URL base fica em HIAPI_BASE_URL, então o mesmo comando funciona em qualquer ambiente.
• Authorization — o token bearer identifica sua conta e é a base da cobrança. Cabeçalho ausente ou malformado é a causa mais comum de 401.
• Content-Type: application/json — o corpo é JSON; sem esse cabeçalho, o servidor rejeitará ou interpretará mal o payload.
• model — seleciona o mirelo-sfx-2.0. Como a HiAPI roteia com base nesse campo, você pode trocar de modelo sem alterar a URL.
• input.prompt — a descrição textual do som. Descrições concretas e físicas (material, ação, ambiente) produzem resultados melhores do que descrições abstratas.

Um envio bem-sucedido não retorna áudio. Ele retorna um objeto de tarefa com um identificador (geralmente o campo id), que você usa para verificar o status. Capture esse ID da resposta; ele é a pista para recuperar o WAV depois.

Se quiser confirmar a estrutura da requisição antes de escrever código, execute esse comando exato no terminal primeiro. Uma vez que funcione, convertê-lo para Python é um trabalho mecânico.

A mesma chamada em Python

A versão em Python mantém a mesma URL, cabeçalhos e corpo — apenas os representa como dicionários e chamadas de cliente:

import os
import requests

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

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

As diferenças em relação à versão em shell:

• Acesso ao ambiente — os.environ substitui a expansão do shell, então a chave nunca aparece no código-fonte.
• json= em vez de -d — o requests serializa o dicionário e define o tipo de conteúdo para você. Você pode remover o cabeçalho manual, embora mantê-lo não faça mal.
• raise_for_status() — converte respostas fora da faixa 2xx em exceções; o tratamento de erros deve ficar aqui.
• timeout — o timeout do cliente evita que conexões travadas pendurem seu processo de trabalho. A criação de tarefas é rápida; a espera longa ocorre durante o polling.

O valor retornado é o ID da tarefa. Guarde-o — é o seu único handle para essa geração. Neste ponto, o caminho Python e o caminho curl se encontram: ambos precisam da etapa de polling para que o áudio exista.

Como o corpo da requisição é apenas dados, você pode parametrizar o prompt e percorrer uma lista de descrições para gerar efeitos sonoros em lote, criando uma tarefa para cada prompt e coletando os IDs.

Tratamento de tarefas assíncronas e polling de resultados

A geração de som leva tempo — na ordem de segundos, não de milissegundos — então a HiAPI a modela como uma tarefa. A chamada de criação retorna um ID imediatamente; um segundo endpoint informa se a tarefa ainda está em execução, foi concluída ou falhou.

O ciclo típico é:

1. Criar a tarefa e capturar o ID.
2. Consultar o endpoint de status da tarefa com esse ID.
3. Se o status ainda for de processamento, aguardar brevemente e consultar novamente.
4. Quando o status indicar sucesso, ler a saída da resposta.
5. Se o status indicar falha, parar e lançar um erro.

Em Python:

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

Alguns pontos merecem destaque:

• Intervalo de polling. Dois segundos é um padrão razoável para efeitos sonoros. Consultar em loop apertado desperdiça cota e pode acionar limites de taxa, sem fazer o resultado chegar mais rápido.
• Prazo total. Sempre defina um limite para o loop. Uma tarefa travada deve fazer seu job falhar, em vez de pendurar o processo de trabalho para sempre.
• Valores de status. Trate valores de status desconhecidos como "ainda em processamento" em vez de assumir sucesso, e ramifique explicitamente nos estados de sucesso e falha.
• Webhooks (se disponíveis). Se sua conta HiAPI suportar callbacks de conclusão, prefira-os ao polling em código de produção no servidor; para scripts e protótipos, o polling continua sendo a opção mais simples.

Guarde o ID da tarefa junto com o prompt no seu próprio banco de dados, para poder tentar novamente, auditar ou recuperar a saída depois sem regenerar.

Leitura da resposta WAV retornada

Quando a tarefa reporta sucesso, a resposta contém o áudio gerado. Dependendo da versão do endpoint, a saída pode vir como URL de arquivo WAV ou como dados de áudio inline; trate ambos os casos como "bytes armazenáveis".

O objeto de tarefa bem-sucedido carrega a saída em um campo como output, geralmente acompanhado de metadados como nome do modelo, prompt original e informações de tempo. O áudio em si é um contêiner WAV padrão, o que significa que você pode entregá-lo a qualquer biblioteca de áudio sem decodificadores personalizados.

Para persistir um resultado baseado em URL:

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Se o áudio chegar como dados codificados, faça a decodificação base64 antes de gravar:

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Depois de obter os bytes:

• Valide o cabeçalho. Arquivos WAV começam com o número mágico RIFF. Verificar os primeiros quatro bytes permite detectar downloads truncados antes que cheguem ao armazenamento.
• Armazenamento persistente. Grave no armazenamento de objetos e salve a chave no banco de dados junto com o ID da tarefa. Trate o áudio gerado como um artefato cacheável, não como uma resposta temporária.
• Reprodução ou processamento. Ferramentas padrão — wave, soundfile ou qualquer player de áudio — abrem o arquivo diretamente. Depois você pode cortar silêncios, normalizar o volume ou converter para outros formatos para entrega.

Como o arquivo é um WAV comum, integrá-lo a um endpoint web ou pipeline de assets de game engine não exige tratamento especial.

Pontos comuns de falha e como corrigi-los

A maioria dos problemas de integração se enquadra em algumas categorias previsíveis.

Erros de autenticação (401 / 403)

401 quase sempre significa que o cabeçalho Authorization está ausente, malformado ou foi construído a partir de uma variável de ambiente vazia. Confirme que HIAPI_API_KEY está exportada no shell em que o processo roda — não apenas no editor — e que o cabeçalho lê Bearer <key>, com exatamente um espaço no meio. 403 geralmente significa que a chave é válida mas não tem acesso a esse modelo; verifique as permissões de modelo da sua conta.

Payload malformado (400 / 422)

A causa mais comum é um corpo de requisição que não é JSON válido — aspas não pareadas no comando curl são o exemplo clássico. Valide com um verificador de JSON antes de enviar. A segunda causa mais comum é a falta do campo model ou um nível de aninhamento errado do prompt; o modelo espera input.prompt, não prompt no nível superior. Por fim, verifique se o prompt não está vazio e se seu comprimento está dentro dos limites definidos na documentação do modelo.

Polling com frequência excessiva

Um loop while apertado sem sleep gera uma enxurrada de requisições de status, pode acionar limites de taxa e deixa mais lenta a tarefa que você está esperando. Use um intervalo fixo de um a dois segundos, adicione jitter ao rodar vários jobs em paralelo e sempre imponha um tempo máximo de espera.

Tratar a criação como conclusão

A resposta de criação parece um sucesso e retorna 200, mas não contém áudio. Se seu código ler o campo output imediatamente, ele falhará ou gravará um arquivo vazio. Sempre passe pelo endpoint de status antes de acessar o resultado.

Timeouts silenciosos e novas tentativas

Repetir uma criação de tarefa após um timeout de rede é seguro, mas repetir a chamada de criação depois de um timeout que na verdade teve sucesso gera jobs duplicados. Se o endpoint suportar chaves de idempotência, use-as; caso contrário, liste as tarefas recentes para conferir antes de tentar novamente.

Casos extremos de disco e armazenamento

Ao gravar os bytes do WAV, abra o arquivo em modo binário ("wb"). O modo texto corrompe o cabeçalho. Se você armazenar a saída pelo nome do prompt, duas tarefas com o mesmo prompt vão se sobrescrever — use o ID da tarefa como chave do arquivo.

Com essas salvaguardas, a integração do mirelo-sfx-2.0 é um pipeline curto: criar, consultar, persistir. Comece pela chamada curl, migre para Python e use o ID da tarefa como sua fonte de verdade.