Music & Sound Effects | Documentazione API Venice

La generazione di musica ed effetti sonori è asincrona. Scegli un modello, richiedi un preventivo, metti in coda la generazione, quindi effettua polling finché Venice non restituisce il file audio finito.

Scegli un modello

Consulta i Modelli Musica ed Effetti Sonori per gli ID dei modelli attuali, i prezzi, i limiti di durata e le funzionalità supportate. Puoi anche scoprire le capacità dei modelli a runtime:

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

Controlla i metadati di ciascun modello prima di impostare campi opzionali come duration_seconds, lyrics_prompt, force_instrumental o loop. I campi non supportati generano una risposta HTTP 400.

Flusso di generazione

Endpoint	Scopo
`POST /audio/quote`	Stima il costo di generazione in USD
`POST /audio/queue`	Avvia una generazione di musica o effetti sonori
`POST /audio/retrieve`	Effettua polling sul job e scarica l’audio completato
`POST /audio/complete`	Elimina i contenuti multimediali archiviati dopo il download

1. Ottieni un preventivo

Richiedi un preventivo prima di generare i contenuti multimediali. Includi lo stesso modello e la stessa durata che intendi inviare all’endpoint di coda.

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

La risposta contiene il costo stimato in USD:

{
  "quote": 0.75
}

2. Metti in coda la generazione

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
  }'

Una richiesta andata a buon fine restituisce il modello e un ID di coda:

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

Salva sia model che queue_id; gli endpoint retrieve e complete li richiedono.

3. Effettua polling e scarica

Chiama /audio/retrieve con i valori ottenuti dalla risposta della coda:

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

Controlla il Content-Type della risposta:

Content-Type	Significato	Azione
`application/json`	La generazione è ancora in corso	Leggi i campi temporali, attendi ed effettua nuovamente il polling
`audio/mpeg`, `audio/wav` o `audio/flac`	La generazione è completata	Salva il corpo binario con l’estensione corrispondente

Una risposta di elaborazione in corso appare così:

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

Entrambi i valori temporali sono in millisecondi.

Esempio completo

Questo esempio in Python mette in coda musica strumentale, effettua polling ogni cinque secondi e salva il risultato con un’estensione basata sul suo 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",
}

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]

    if content_type in content_type_to_extension:
        output = Path("generated-audio" + content_type_to_extension[content_type])
        output.write_bytes(result.content)
        print(f"Saved {output}")
        break

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

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

L’endpoint quote non richiede autenticazione, mentre le richieste queue, retrieve e complete sì.

Consigli per i prompt

Per la musica, descrivi genere, strumenti, atmosfera, tempo, struttura e se desideri la presenza di voci.
Per gli effetti sonori, descrivi la sorgente, l’ambiente, l’intensità, il tempismo e la prospettiva.
Usa lyrics_prompt solo quando il modello selezionato supporta i testi.
Usa force_instrumental o loop solo quando i metadati del modello ne segnalano il supporto.

Documentazione

Per iniziare

Testo e chat

Immagini, video e audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Musica ed Effetti Sonori

Scegli un modello

Flusso di generazione

1. Ottieni un preventivo

2. Metti in coda la generazione

3. Effettua polling e scarica

Esempio completo

Consigli per i prompt

Risorse correlate

​Scegli un modello

​Flusso di generazione

​1. Ottieni un preventivo

​2. Metti in coda la generazione

​3. Effettua polling e scarica

​Esempio completo

​Consigli per i prompt

​Risorse correlate

Scegli un modello

Flusso di generazione

1. Ottieni un preventivo

2. Metti in coda la generazione

3. Effettua polling e scarica

Esempio completo

Consigli per i prompt

Risorse correlate