Voice Changer

Il Voice Changer è speech-to-speech: registra di nuovo un file sorgente in una voce diversa preservando pronuncia, ritmo e tempistica. È asincrono e usa endpoint dedicati, non /audio/queue, e nemmeno text-to-speech o voice cloning. Scegli un modello voice-changer, richiedi un preventivo, metti in coda la conversione, quindi effettua polling finché Venice non restituisce l’audio convertito.

Una conversione messa in coda viene addebitata immediatamente. Se la risposta della coda viene persa, esegui il polling di /audio/voice-changer/retrieve con lo stesso queue_id. Non mettere in coda di nuovo la stessa registrazione.

Scegli un modello

I modelli voice-changer sono restituiti da GET /models?type=music con model_spec.voice_changer impostato su true. Non esiste un filtro ?type=voice-changer. Gli esempi seguenti usano elevenlabs-voice-changer.

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:

Campo	Uso
`voices` / `default_voice`	Nomi delle voci di destinazione. Ometti `voice` per usare quella predefinita.
`supports_custom_voice_id`	Indica se `voice` accetta anche un Voice ID del provider
`accepted_audio_formats`	Contenitori sorgente accettati da Venice (validati dalla firma binaria del file, non dal nome)
`max_source_audio_duration_seconds`	Registrazione sorgente più lunga accettata dal modello
`supports_background_noise_removal`	Indica se `remove_background_noise` è accettato
`supports_seed`	Indica se `seed` è accettato
`pricing.durations`	Fasce di prezzo per minuti interi

I campi non supportati generano una risposta HTTP 400. Le registrazioni più lunghe di max_source_audio_duration_seconds vengono rifiutate con HTTP 422 prima di qualsiasi addebito.

Flusso di conversione

Endpoint	Scopo
`POST /audio/voice-changer/quote`	Stima il costo della conversione in USD
`POST /audio/voice-changer/queue`	Avvia una conversione speech-to-speech
`POST /audio/voice-changer/retrieve`	Effettua polling sul job e scarica l’audio convertito
`POST /audio/voice-changer/complete`	Elimina i media memorizzati dopo il download

1. Ottieni un preventivo

Il Voice Changer viene fatturato in base alla durata della registrazione sorgente, arrotondata per eccesso al minuto intero successivo. Richiedi un preventivo per la durata che prevedi di inviare; l’addebito viene calcolato dalla durata misurata da Venice quando la registrazione viene messa in coda.

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

La risposta contiene il costo stimato in USD e la durata per cui il preventivo è stato calcolato:

{
  "quote": 0.35,
  "duration_seconds": 60
}

2. Metti in coda la conversione

Fornisci la registrazione sorgente esattamente in uno di due modi: come upload multipart file, oppure come audio_url in un corpo JSON. Fornire entrambi, o nessuno dei due, viene rifiutato. Quando passi un URL, Venice scarica e valida i byte da sola e inoltra al provider solo quei byte. L’URL non viene mai inoltrato.

curl https://api.venice.ai/api/v1/audio/voice-changer/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -F "model=elevenlabs-voice-changer" \
  -F "voice=Aria" \
  -F "file=@./source-recording.mp3"

curl https://api.venice.ai/api/v1/audio/voice-changer/queue \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-voice-changer",
    "voice": "Aria",
    "audio_url": "https://example.com/source-recording.mp3"
  }'

Campi opzionali, quando il modello ne segnala il supporto:

remove_background_noise — rimuove il rumore di fondo prima della conversione
seed — intero ≥ 0 per un risultato riproducibile

Una richiesta andata a buon fine restituisce il modello, un ID di coda e la durata misurata della sorgente:

{
  "model": "elevenlabs-voice-changer",
  "queue_id": "0190f2c4-9c1e-7a3b-8f42-2c9d5e7a1b34",
  "status": "QUEUED",
  "duration_seconds": 52
}

Salva model e queue_id; gli endpoint retrieve e complete li richiedono. Confronta duration_seconds con il tuo preventivo se hai bisogno di riconciliare la stima con la durata fatturata.

La coda non è sicura da ritentare. Una richiesta di coda andata a buon fine è già stata addebitata.

3. Effettua polling e scarica

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

curl https://api.venice.ai/api/v1/audio/voice-changer/retrieve \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs-voice-changer",
    "queue_id": "0190f2c4-9c1e-7a3b-8f42-2c9d5e7a1b34"
  }' \
  --output response.bin

Controlla il Content-Type della risposta:

Content-Type	Significato	Azione
`application/json`	La conversione è ancora in corso	Leggi i campi temporali, attendi ed effettua nuovamente il polling
`audio/mpeg`	La conversione è completata	Salva il corpo binario come `.mp3`

Una risposta di elaborazione in corso appare così:

{
  "status": "PROCESSING",
  "average_execution_time": 10000,
  "execution_duration": 4200
}

Entrambi i valori temporali sono in millisecondi. Una risposta completata include anche x-venice-audio-format, x-venice-audio-duration, x-venice-inference-time, x-venice-model-id e x-venice-model-name. Se il provider non riesce a completare la conversione, l’addebito viene rimborsato automaticamente e il corpo dell’errore include credits_refunded. Un polling successivo restituisce lo stesso risultato invece di rimborsare due volte. Per eliminare i media memorizzati nella stessa chiamata che restituisce l’audio, imposta delete_media_on_completion su true su retrieve. L’audio non potrà essere recuperato di nuovo in seguito.

Esempio completo

Questo esempio in Python richiede un preventivo di conversione, carica un file sorgente, effettua polling ogni cinque secondi e salva il risultato come MP3.

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']}",
}

source = Path("source-recording.mp3")

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

with source.open("rb") as audio:
    queued = requests.post(
        f"{BASE_URL}/audio/voice-changer/queue",
        headers=HEADERS,
        data={
            "model": "elevenlabs-voice-changer",
            "voice": "Aria",
        },
        files={"file": audio},
    )
queued.raise_for_status()
job = queued.json()
print(f"Queued {job['queue_id']} ({job['duration_seconds']}s billed)")

while True:
    result = requests.post(
        f"{BASE_URL}/audio/voice-changer/retrieve",
        headers={**HEADERS, "Content-Type": "application/json"},
        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 == "audio/mpeg":
        output = Path("converted-audio.mp3")
        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/voice-changer/complete",
    headers={**HEADERS, "Content-Type": "application/json"},
    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ì.

Documentazione

Per iniziare

Testo e chat

Immagini

Video

Audio

Ricerca e RAG

Agenti e integrazioni

Strumenti di sviluppo

Strumenti per agenti

SDK e framework

Scegli un modello

Flusso di conversione

1. Ottieni un preventivo

2. Metti in coda la conversione

3. Effettua polling e scarica

Esempio completo

Risorse correlate

​Scegli un modello

​Flusso di conversione

​1. Ottieni un preventivo

​2. Metti in coda la conversione

​3. Effettua polling e scarica

​Esempio completo

​Risorse correlate

Scegli un modello

Flusso di conversione

1. Ottieni un preventivo

2. Metti in coda la conversione

3. Effettua polling e scarica

Esempio completo

Risorse correlate