Música e Efeitos Sonoros

A geração de música e efeitos sonoros é assíncrona. Escolha um modelo, solicite uma cotação de preço, coloque a geração na fila e faça polling até que a Venice retorne o arquivo de áudio finalizado.

Modelos de trocador de voz não são aceitos nesses endpoints. Converta uma gravação de origem com a API do Trocador de Voz em vez disso.

Escolha um modelo

Consulte Modelos de Música e Efeitos Sonoros para ver os IDs de modelos atuais, preços, limites de duração e recursos suportados. Você também pode descobrir as capacidades dos modelos em tempo de execução:

curl "https://api.venice.ai/api/v1/models?type=music" \
  -H "Authorization: Bearer $VENICE_API_KEY"

Verifique os metadados de cada modelo antes de definir campos opcionais como duration_seconds, lyrics_prompt, force_instrumental ou loop. Campos não suportados causam uma resposta HTTP 400.

Fluxo de geração

Endpoint	Finalidade
`POST /audio/quote`	Estimar o custo de geração em USD
`POST /audio/queue`	Iniciar uma geração de música ou efeito sonoro
`POST /audio/retrieve`	Consultar o job e baixar o áudio concluído
`POST /audio/complete`	Excluir a mídia armazenada após baixá-la

1. Obtenha uma cotação de preço

Cote a requisição antes de gerar a mídia. Inclua o mesmo modelo e duração que você planeja enviar ao endpoint de fila.

curl https://api.venice.ai/api/v1/audio/quote \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "duration_seconds": 30
  }'

A resposta contém o custo estimado em USD:

{
  "quote": 0.69
}

Alguns modelos cobram por faixas de duração, então uma requisição de 30 segundos ao elevenlabs-music é cobrada pela faixa de 60 segundos. Confira o pricing de cada modelo em GET /models?type=music para ver suas faixas ou o preço por segundo.

2. Coloque a geração na fila

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": true
  }'

curl https://api.venice.ai/api/v1/audio/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-sound-effects-v2",
    "prompt": "Ocean waves rolling onto a pebble beach at night",
    "duration_seconds": 10
  }'

Uma requisição bem-sucedida retorna o modelo e um ID de fila:

{
  "model": "elevenlabs-music",
  "queue_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "QUEUED"
}

Salve tanto model quanto queue_id; os endpoints retrieve e complete os exigem.

3. Faça polling e baixe

Chame /audio/retrieve com os valores da resposta de fila:

curl https://api.venice.ai/api/v1/audio/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-music",
    "queue_id": "123e4567-e89b-12d3-a456-426614174000"
  }' \
  --output response.bin

Inspecione o Content-Type da resposta:

Content-Type	Significado	Ação
`application/json`	A geração ainda está em processamento	Leia os campos de tempo, aguarde e faça polling novamente
Qualquer outro tipo, como `audio/mpeg`, `audio/wav`, `audio/flac` ou `audio/mp4`	A geração está concluída	Salve o corpo binário com a extensão correspondente (`.m4a` para `audio/mp4`)

O tipo de áudio depende do formato de saída do modelo. Confira default_format e supported_formats nos metadados do modelo; por exemplo, modelos que geram m4a retornam audio/mp4. Uma resposta de processamento se parece com esta:

{
  "status": "PROCESSING",
  "average_execution_time": 20000,
  "execution_duration": 5200
}

Ambos os valores de tempo estão em milissegundos.

Exemplo completo

Este exemplo em Python coloca música instrumental na fila, faz polling a cada cinco segundos e salva o resultado com uma extensão baseada em seu content type.

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

generation = {
    "model": "elevenlabs-music",
    "prompt": "Warm cinematic strings with a gentle piano melody, hopeful and spacious",
    "duration_seconds": 30,
    "force_instrumental": True,
}

quote = requests.post(f"{BASE_URL}/audio/quote", json={
    "model": generation["model"],
    "duration_seconds": generation["duration_seconds"],
})
quote.raise_for_status()
print(f"Estimated cost: ${quote.json()['quote']:.2f}")

queued = requests.post(f"{BASE_URL}/audio/queue", headers=HEADERS, json=generation)
queued.raise_for_status()
job = queued.json()

content_type_to_extension = {
    "audio/mpeg": ".mp3",
    "audio/wav": ".wav",
    "audio/flac": ".flac",
    "audio/mp4": ".m4a",
}

while True:
    result = requests.post(
        f"{BASE_URL}/audio/retrieve",
        headers=HEADERS,
        json={"model": job["model"], "queue_id": job["queue_id"]},
    )
    result.raise_for_status()
    content_type = result.headers.get("Content-Type", "").split(";")[0].strip()

    if content_type == "application/json":
        status = result.json()
        print(f"Status: {status['status']}")
        time.sleep(5)
        continue

    extension = content_type_to_extension.get(content_type, ".bin")
    output = Path("generated-audio" + extension)
    output.write_bytes(result.content)
    print(f"Saved {output}")
    break

requests.post(
    f"{BASE_URL}/audio/complete",
    headers=HEADERS,
    json={"model": job["model"], "queue_id": job["queue_id"]},
).raise_for_status()

O endpoint de cotação não requer autenticação, mas as requisições de queue, retrieve e complete requerem.

Dicas de prompt

Para música, descreva gênero, instrumentos, clima, andamento, estrutura e se vocais são desejados.
Para efeitos sonoros, descreva a fonte, o ambiente, a intensidade, o timing e a perspectiva.
Use lyrics_prompt somente quando o modelo selecionado suportar letras.
Use force_instrumental ou loop somente quando os metadados do modelo indicarem suporte.

Documentação

Primeiros passos

Texto e chat

Imagem

Vídeo

Áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

Escolha um modelo

Fluxo de geração

1. Obtenha uma cotação de preço

2. Coloque a geração na fila

3. Faça polling e baixe

Exemplo completo

Dicas de prompt

Recursos relacionados

​Escolha um modelo

​Fluxo de geração

​1. Obtenha uma cotação de preço

​2. Coloque a geração na fila

​3. Faça polling e baixe

​Exemplo completo

​Dicas de prompt

​Recursos relacionados

Escolha um modelo

Fluxo de geração

1. Obtenha uma cotação de preço

2. Coloque a geração na fila

3. Faça polling e baixe

Exemplo completo

Dicas de prompt

Recursos relacionados