Como usar a API do Mirelo SFX 2.0? Gere seu primeiro efeito sonoro em 5 minutos

TL;DR

• O que é: modelo de efeitos sonoros a partir de texto; uma descrição gera um WAV de 1 a 30 segundos (PCM 16-bit / 48 kHz / mono). Abra a página do modelo Mirelo SFX 2.0 e escreva uma frase para ouvir uma prévia. O Mirelo SFX 2.0 já está disponível no HiAPI, e novos usuários ganham 200 créditos ao se registrar.
• Quanto custa: cobrança por segundo de saída, a $0.0215 por segundo (43 créditos), com mínimo de 1 segundo; 5 segundos custam $0.1075, 30 segundos custam $0.645.
• Como chamar mais rápido: na página do modelo, preencha a descrição, escolha a duração e envie; para integrar ao seu produto, use POST /v1/tasks, preencha model com mirelo-sfx-2.0 e coloque em input apenas prompt e duration.

O que é o Mirelo SFX 2.0

A entrada tem apenas dois campos: prompt e duration. A descrição vai de 1 a 2.000 caracteres; especifique a fonte sonora, o material, a ação, a distância e o ambiente, e acrescente o ataque e a cauda; duration é um número inteiro de 1 a 30 segundos, com padrão 5. A saída é sempre um único WAV, PCM 16-bit, 48 kHz, mono, sem opções de formato.

Ele gera apenas efeitos sonoros isolados e ambiências: um evento sonoro por requisição, sem gerar músicas, vozes ou diálogos. Cobrir um ponto de impacto na edição, criar um som de feedback de UI para um jogo, ou produzir um ruído de fundo de noite chuvosa para um vídeo curto — tudo isso é com ele.

O exemplo de martelada no site entrega 1 segundo por $0.0215. O transiente e a reverberação metálica cabem nesse segundo:

Ouvir: golpe de martelo em viga de aço, WAV de 1 segundo

A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.

Gerar com este prompt → O link apenas preenche a descrição; depois de abrir, defina duration como 1 segundo para obter este resultado.

Ouça também um caso de ambiência de 10 segundos, com o mesmo modelo e o mesmo conjunto de campos:

Ouvir: telhado metálico em noite de chuva, WAV de 10 segundos

Teste online: 4 passos para ouvir o primeiro

1. Abra a página do modelo Mirelo SFX 2.0; ao se registrar, você recebe 200 créditos.
2. Cole a descrição de martelada acima na caixa de descrição, ou substitua pelo som que você quer.
3. Defina duration como 1 a 3 segundos e ouça primeiro o ataque e a cauda.
4. Clique em enviar; o que aparece no player é o WAV, que pode ser baixado diretamente.

Não pule o passo 3. A mesma descrição em 1 segundo e em 10 segundos produz coisas diferentes; começar curto e depois alongar economiza o dinheiro de gerações repetidas.

Integração via API: 4 passos para funcionar

1. Crie uma API Key no console.
2. POST https://api.hiapi.ai/v1/tasks, com model definido como mirelo-sfx-2.0 e input contendo prompt e duration.
3. Pegue o taskId retornado e aguarde a notificação de callback, ou consulte GET /v1/tasks/{taskId} repetidamente.
4. Quando status virar success, pegue em output o item cujo type é audio e baixe o WAV pela url dele.

curl executável

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
      "duration": 1
    }
  }'

O ID da tarefa na resposta fica em data.taskId:

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

Use esse ID para consultar o status:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status passa por queued, handling, success ou fail. Em caso de sucesso, procure em data.output o item cujo type é audio.

Versão em Python: criar, consultar e baixar de uma vez

import requests
import time

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "mirelo-sfx-2.0",
    "input": {
        "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
        "duration": 1,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    audio_url = next(item["url"] for item in data["output"] if item["type"] == "audio")
    with open("effect.wav", "wb") as f:
        f.write(requests.get(audio_url, timeout=60).content)
    print("saved effect.wav")
else:
    print(data.get("error"))

Tarefas de efeitos sonoros são bem mais curtas que as de vídeo; um intervalo de 2 segundos entre consultas já basta, não precisa esperar os 3 segundos completos.

Como escrever a descrição: cinco elementos

Não há parâmetros extras; o prompt é toda a superfície de controle. Escreva seguindo estes cinco itens para acertar de primeira:

Elemento	O que escrever	Frase correspondente no exemplo
Fonte sonora	O que está emitindo o som	a heavy hammer strike
Material	O material do corpo que emite o som	on a steel beam
Ação	Como o som é produzido, com que intensidade	single, heavy
Distância e ambiente	Onde está o ouvinte, qual o tamanho do espaço	in a large empty warehouse, close perspective
Ataque e cauda	Quão rápido é o início, quão longa é a terminação	sharp transient, long metallic ring

Se não tiver certeza de alguma dimensão, omita-a; evite adjetivos como "mais ou menos" ou "cinematográfico" — cada substantivo concreto na descrição se traduz em som. Vale incluir uma frase final como "no music and no voices", que exclui de uma vez as camadas indesejadas.

Como escolher a duração

Primeiro use 1 a 3 segundos para confirmar se o timbre, o ataque e a cauda estão certos; ao finalizar, aumente duration para o comprimento desejado. A mesma descrição em 3 segundos e em 10 segundos tem densidades de eventos diferentes; a versão curta serve para testar a direção, a longa para o produto final, o que é bem mais barato do que rodar 30 segundos direto.

• Impactos, UI, cliques → 1 a 3 segundos.
• Ambiências, ruído de fundo, atmosfera de sala → 10 a 30 segundos.
• Para casar com a duração do plano → preencha diretamente com o número inteiro de segundos do plano; o modelo entrega a duração informada.

4 coisas a observar antes de ir para produção

1. Callback com consulta como garantia. Adicione ao corpo da requisição "callback": {"url": "https://yourapp.com/webhook", "when": "final"}; a tarefa notificará você ao entrar no estado final. Como a notificação pode se perder, configure também um GET /v1/tasks/{taskId} periódico como compensação.
2. Idempotência por taskId. success e fail são estados finais, e o mesmo taskId pode receber notificações múltiplas; consulte o banco para deduplicar antes de processar.
3. Os links dos artefatos expiram. A url em output é um endereço temporário; ao recebê-la, transfira para o seu próprio armazenamento, não a use como CDN de longo prazo.
4. Uma descrição, um evento. Impacto mais fragmentos caindo, chuva mais trovão mais latido de cachorro — divida em várias requisições e gere separadamente, sobrepondo na pós-produção; é mais controlável do que espremer tudo em uma frase.

Perguntas frequentes

O Mirelo SFX 2.0 gera músicas ou vozes? Não. Ele só faz efeitos sonoros isolados e ambiências, com duração máxima de 30 segundos. Para trilha sonora, use um modelo de música; para narração, um modelo de voz.

O que acontece se duration não for preenchido? Gera com 5 segundos e cobra $0.1075. Para outra duração, escreva explicitamente, como um inteiro de 1 a 30.

Dá para escolher MP3 ou estéreo na saída? Não; é sempre um único WAV, PCM 16-bit, 48 kHz, mono. Para outro formato, converta na pós-produção.

Qual é o tamanho máximo da descrição? 2.000 caracteres, suficiente para incluir uma especificação sonora completa.

Rode o primeiro agora

Copie a descrição de martelada acima, abra a página do modelo Mirelo SFX 2.0, defina duration como 1 segundo e ouça um impacto completo por $0.0215. Depois de confirmar o resultado, coloque os mesmos dois campos no curl acima e integre ao seu próprio fluxo. Para os parâmetros completos, veja a documentação de integração.

Leitura relacionada: Preço do Mirelo SFX 2.0 · vs ElevenLabs Sound Effects v2 · 4 prompts reais de efeitos sonoros