Skip to main content
POST
Clona e salva una voce personalizzata da 1–3 file audio caricati di tua proprietà. È richiesta un’autorizzazione esplicita. I campioni devono durare complessivamente 10–120 secondi e ciascuno non deve superare 20 MB. Si applicano i limiti di voci del piano.

​
Autenticazione e autorizzazioni

​
string
obbligatorio
Invia una chiave API VoiceCheap in questa intestazione. È supportato anche Authorization: Bearer con la stessa chiave API. I token di accesso OAuth sono accettati solo da MCP, non da questo endpoint REST.
Autorizzazioni richieste: voices:write. È necessario un abbonamento a pagamento attivo. Le autorizzazioni non modificano i ruoli del team, la proprietà delle risorse, i crediti multimediali o i limiti del piano.

​
Parametri

​
string
Facoltativo al livello di trasporto: se omesso, il server inserisce un identificatore prima della validazione. Fornisci un tuo UUID v4 stabile per recuperare in sicurezza una risposta persa.Formato: “uuid”. Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
​
string
obbligatorio
Valore testuale.Lunghezza minima: 1. Lunghezza massima: 80.
​
array
obbligatorio
Elenco di valori. Consulta lo schema di input completo per la struttura degli elementi.Numero minimo di elementi: 1. Numero massimo di elementi: 3.
​
boolean
obbligatorio
Conferma di avere il permesso di clonare la persona la cui voce è presente in ciascun campione.Valore obbligatorio: true.
​
boolean
Valore booleano.Valore predefinito: false.
​
string
Valore testuale.Lunghezza massima: 35. Pattern: ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$.
Il JSON Schema seguente conserva i nomi esatti dei campi, i tipi annidati, i valori predefiniti, i limiti e i valori accettati esposti dalla discovery. Le ulteriori regole tra campi sono elencate nelle note sull’operazione.

​
Idempotenza

Usa un UUID v4 in requestId o nell’intestazione HTTP Idempotency-Key per ogni modifica. Riutilizza lo stesso identificatore e argomenti identici dopo un errore di rete. Se vengono forniti entrambi, devono coincidere. Ripetere una richiesta salvata non ripete l’operazione e non consuma un’altra chiamata mensile. Le richieste non riuscite o interrotte non vengono riavviate automaticamente. Ogni modifica può restituire HTTP 202 quando un nuovo tentativo trova la stessa richiesta ancora in esecuzione, anche se la prima esecuzione è normalmente sincrona. Se l’esecuzione è completata ma resultStored è false, un nuovo tentativo restituisce HTTP 200 con lo stato della richiesta salvata anziché il risultato originale. Recupera l’output tramite l’azione di cronologia, risultato o download del relativo dominio.

​
Esempi di richiesta

Sostituisci gli identificatori delle risorse e le chiavi multimediali di esempio con i valori restituiti per il tuo account. Mantieni stabile l’identificatore della richiesta quando ripeti la stessa modifica.

​
Risposta

Questa operazione restituisce HTTP 202 mentre è in esecuzione. Salva requestId e interroga action_request_get con questo identificatore e il nome dell’operazione originale. Gli stati del polling sono running, completed, failed e interrupted. Un risultato completato può rimandare a un processo multimediale separato; prosegui con l’azione di stato o di output specifica dell’operazione. La voce TTS personalizzata salvata e riutilizzabile e la quota aggiornata degli slot di salvataggio.

​
Campi del risultato

​
Recupera e monitora questa richiesta

Usa lo stesso identificatore anche dopo una connessione persa. Se resultStored è false, recupera l’output tramite la corrispondente azione di cronologia, risultato o download. Non avviare mai una seconda generazione solo per verificarne l’avanzamento.
HTTP 200

​
Note sull’operazione

  • Usa un requestId UUID v4 per questa modifica e riutilizzalo con argomenti identici nei nuovi tentativi. Le azioni di lunga durata restituiscono inizialmente una richiesta in stato running; questo esempio è il risultato del gestore completato disponibile da action_request_get.
  • Carica 1–3 campioni audio di proprietà dell’utente e usa i relativi valori fileKey completati. I formati dei campioni supportati sono MP3, WAV, M4A, OGG e Opus; ogni file deve essere non vuoto e avere una dimensione massima di 20 MiB (20,971,520 byte). Gli URL remoti e i caricamenti di altri account vengono rifiutati.
  • I campioni devono totalizzare almeno 10 secondi e al massimo 120 secondi di audio leggibile. Il valore predefinito di trimToMaxDuration è false; impostalo su true per accorciare proporzionalmente i campioni che totalizzano più di 120 secondi.
  • hasPermission deve essere il booleano JSON true, a conferma del permesso per ogni campione. Un valore stringa come “true” viene rifiutato.
  • name deve contenere 1–80 caratteri dopo la rimozione degli spazi iniziali e finali. Il campo opzionale language accetta un codice di 2–3 lettere con eventuali sottotag e un massimo di 35 caratteri.
  • Questa azione salva direttamente la voce clonata e occupa uno slot per voci TTS salvate. Non consuma la prova una tantum dell’anteprima di clonazione.
  • Usa il voice.id restituito in tts_generate. Per una clonazione diretta, il relativo UUID è il requestId; voices_delete accetta tale UUID senza il prefisso clone:.
  • Il campo language accettato non modifica il flusso di clonazione con salvataggio diretto. Scegli voices_preview_clone quando serve un testo di anteprima specifico per una lingua.
  • La cronologia dell’audio vocale e le voci personalizzate appartengono all’account autenticato. La fatturazione del team non concede accesso all’audio vocale o alle voci di un altro membro.

​
Utilizzo

Ogni invocazione riuscita consuma una chiamata API/MCP mensile. Si applicano anche i crediti multimediali e le quote di generazione proprie dell’operazione.

​
Errori