ElevenLabs Sound Effects v2 API: gerar e baixar efeitos sonoros

TL;DR

• O ElevenLabs Sound Effects v2 converte uma descrição textual em um efeito sonoro MP3; abra a página do modelo para ouvir os exemplos existentes.
• A cobrança é por duração solicitada: US$ 0,0029 por segundo; 2 segundos custam US$ 0,0058. O preço foi verificado em 25 de outubro de 2026; ver preços.
• Envie a tarefa pela API /v1/tasks do HiAPI para obter o taskId e depois consulte o resultado.

Antes de executar o exemplo em Python, rode python -m pip install requests no mesmo ambiente Python.

Ouça primeiro um exemplo de dois segundos

Este é o exemplo de impacto grave cinematográfico já disponível na página do modelo; abaixo mantemos o prompt completo e o áudio.

Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.

Ouvir o efeito sonoro completo

Gerar com este prompt →

elevenlabs/sound-effects-v2, 2 segundos, prompt_influence: 0.3, loop: false, MP3, pelo preço atual de US$ 0,0058. Após abrir o link pré-preenchido, defina separadamente a duração e os controles.

Como preencher os parâmetros

Campo	Obrigatório	Valores e descrição
model	Sim	elevenlabs/sound-effects-v2, no nível superior do corpo da requisição
input.prompt	Sim	1–450 caracteres, descrevendo som, material, ação e espaço
input.duration_seconds	Sim	0,5–22 segundos, aceita decimais; deve ser preenchido explicitamente
input.prompt_influence	Não	0–1, padrão 0.3
input.loop	Não	Booleano, padrão false

Cada retorno traz um MP3 de 44,1 kHz a 128 kbps. loop serve para aproximar o início e o fim, mas não prolonga o áudio; sons de fundo longos devem ser repetidos pelo reprodutor.

curl: enviar o primeiro efeito sonoro

Executar o exemplo cria uma tarefa real e gera cobrança por duração. Coloque a chave na variável de ambiente do servidor HIAPI_API_KEY. Reutilize a chave de idempotência em novas tentativas da mesma requisição de negócio; use uma nova chave para uma nova requisição de efeito sonoro.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sfx-example-001" \
  -d '
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}'

Obtenha o ID da tarefa em data.taskId da resposta de criação e depois consulte GET /v1/tasks/<taskId>.

Python: enviar, aguardar e salvar

Depois de instalar requests, execute o exemplo abaixo. Considere apenas success e fail como estados finais; queued, handling e archiving exigem continuar aguardando.

import json
import os
import time
from pathlib import Path
import requests

api = "https://api.hiapi.ai"
key = os.environ.get("HIAPI_API_KEY", "")
if not key or any(ord(c) < 33 or ord(c) > 126 for c in key) or any(c in key for c in (chr(34), chr(39))):
    raise SystemExit("Check the key environment variable; do not print its value")
headers = {"Authorization": f"Bearer {key}"}
payload = json.loads(r'''
{
  "model": "elevenlabs/sound-effects-v2",
  "input": {
    "prompt": "Spacious cinematic braam with a deep sub-bass impact, metallic shimmer and a short reverb tail, suitable for a high-impact movie trailer moment.",
    "duration_seconds": 2,
    "prompt_influence": 0.3,
    "loop": false
  }
}
''')
response = requests.post(
    f"{api}/v1/tasks", json=payload,
    headers={**headers, "Idempotency-Key": "sfx-example-001"}, timeout=30,
)
response.raise_for_status()
task_id = response.json()["data"]["taskId"]
Path("task-id.txt").write_text(task_id, encoding="utf-8")
print("Task ID saved to task-id.txt:", task_id)
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    response = requests.get(f"{api}/v1/tasks/{task_id}", headers=headers, timeout=30)
    response.raise_for_status()
    task = response.json()["data"]
    if task["status"] == "fail":
        raise RuntimeError(task.get("error", "Task failed"))
    if task["status"] == "success":
        audio = next(item for item in task["output"] if item.get("type") == "audio")
        result = requests.get(audio["url"], timeout=120)
        result.raise_for_status()
        Path("effect.mp3").write_bytes(result.content)
        print("Saved effect.mp3")
        break
    time.sleep(4)
else:
    raise TimeoutError(f"Keep this taskId for later lookup: {task_id}")

Três verificações antes de ir para produção

1. Falhas e timeouts. Verifique o status HTTP e o erro da tarefa; o exemplo preserva o taskId após o timeout da espera para consultas posteriores, evitando envios duplicados.
2. Erros de parâmetro. Em caso de 400 INVALID_REQUEST, verifique a duração obrigatória, os intervalos de valores e os tipos dos campos; não repita a requisição como está. A cobrança provisória de tarefas com falha é reembolsada.
3. Salvamento do resultado. Após o sucesso, leia a URL do áudio e salve-a imediatamente. Tarefas em lote também podem configurar callback.url para receber notificações de estado final.

Perguntas frequentes

Qual é a duração máxima do efeito sonoro gerado?

Cada geração tem de 0,5 a 22 segundos, aceita segundos fracionários e duration_seconds é obrigatório.

O loop prolonga automaticamente o efeito sonoro?

Não. Ele serve para melhorar a transição entre início e fim; a duração continua definida por duration_seconds.

Quanto custa um efeito sonoro de dois segundos?

A US$ 0,0029 por segundo, dois segundos custam US$ 0,0058; tarefas com falha reembolsam a cobrança provisória.

Quando é possível baixar o áudio?

Aguarde status igual a success e leia o item com type igual a audio em output; durante a fase archiving, continue aguardando.

Continue a integração

• Documentação completa do modelo
• Estados de tarefa e callbacks
• Solução de erros de chave
• Copie o prompt do exemplo e crie o efeito sonoro na página do modelo