> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Clona e salva una voce > 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. 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. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/voices_clone ``` ## Autenticazione e autorizzazioni 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 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}$`. Valore testuale. Lunghezza minima: 1. Lunghezza massima: 80. Elenco di valori. Consulta lo schema di input completo per la struttura degli elementi. Numero minimo di elementi: 1. Numero massimo di elementi: 3. Conferma di avere il permesso di clonare la persona la cui voce è presente in ciascun campione. Valore obbligatorio: true. Valore booleano. Valore predefinito: false. 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. ```json theme={null} { "type": "object", "properties": { "requestId": { "description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.", "type": "string", "format": "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}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "samples": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "fileKey": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "An uploaded audio fileKey returned by voices_upload_complete for this account." } }, "required": ["fileKey"], "additionalProperties": false } }, "hasPermission": { "type": "boolean", "const": true, "description": "Confirm that you have permission to clone the person whose voice is in every sample." }, "trimToMaxDuration": { "default": false, "type": "boolean" }, "language": { "type": "string", "maxLength": 35, "pattern": "^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$" } }, "required": ["name", "samples", "hasPermission"], "additionalProperties": false } ``` ## 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. ```bash cURL theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_clone' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"33333333-3333-4333-8333-333333333333","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false}' ``` ```javascript JavaScript theme={null} const input = { requestId: '33333333-3333-4333-8333-333333333333', name: 'Studio narrator', samples: [ { fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav', }, ], hasPermission: true, trimToMaxDuration: false, }; const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_clone', { method: 'POST', headers: { 'x-api-key': process.env.VOICECHEAP_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify(input), }); const body = await response.json(); if (!response.ok) throw new Error(body.code + ': ' + body.message); console.log(body); ``` ```python Python theme={null} import os import requests response = requests.post( "https://api.voicecheap.ai/v1/actions/voices_clone", headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]}, json={"requestId": "33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False}, timeout=120, ) body = response.json() if not response.ok: raise RuntimeError(f"{body.get('code')}: {body.get('message')}") print(body) ``` ## 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. ```json HTTP 202 theme={null} { "data": { "requestId": "33333333-3333-4333-8333-333333333333", "status": "running", "pollAction": "action_request_get", "pollAfterSeconds": 5 }, "requestId": "33333333-3333-4333-8333-333333333333" } ``` ```json HTTP 200 theme={null} { "data": { "voice": { "accent": "original", "id": "clone:33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "previewUrl": "https://files.example.com/saved-narrator.mp3", "source": "clone" }, "cloneUsage": { "canClone": true, "limit": 10, "remaining": 9, "used": 1 } }, "requestId": "33333333-3333-4333-8333-333333333333" } ``` ```json HTTP 202 replay_running theme={null} { "data": { "requestId": "33333333-3333-4333-8333-333333333333", "operation": "voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "running", "pollAfterSeconds": 5 }, "requestId": "33333333-3333-4333-8333-333333333333" } ``` ```json HTTP 200 replay_completed_without_result theme={null} { "data": { "requestId": "33333333-3333-4333-8333-333333333333", "operation": "voices_clone", "createdAt": 1792144800000, "updatedAt": 1792144820000, "status": "completed", "resultStored": false, "message": "The action completed. Retrieve its output from the corresponding history or resource action." }, "requestId": "33333333-3333-4333-8333-333333333333" } ``` ## Campi del risultato | Campo | Descrizione | | - | - | | `data.voice.id` | ID di selezione TTS riutilizzabile clone:\. Usa il valore completo per tts\_generate e solo l'UUID per voices\_delete. | | `data.voice.name` | Nome visualizzato della voce salvata. | | `data.voice.accent` | Le voci personalizzate salvate usano original. | | `data.voice.source` | Le voci personalizzate salvate utilizzano clone. | | `data.voice.previewUrl` | URL temporaneo di anteprima audio per la voce salvata. | | `data.cloneUsage.canClone` | Indica se il piano attuale consente voci TTS personalizzate salvate; controlla remaining per gli slot disponibili. | | `data.cloneUsage.limit` | Limite del piano per gli slot di voci TTS personalizzate salvate. | | `data.cloneUsage.used` | Slot di voci TTS occupati, incluse le creazioni prenotate. | | `data.cloneUsage.remaining` | Slot disponibili per le voci TTS salvate. | ## 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. ```bash theme={null} curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \ --header "x-api-key: $VOICECHEAP_API_KEY" \ --header 'Content-Type: application/json' \ --data '{"requestId":"33333333-3333-4333-8333-333333333333","operation":"voices_clone"}' ``` ```json HTTP 200 theme={null} { "data": { "requestId": "33333333-3333-4333-8333-333333333333", "operation": "voices_clone", "status": "completed", "createdAt": 1792144800000, "updatedAt": 1792144820000, "resultStored": true, "result": { "voice": { "accent": "original", "id": "clone:33333333-3333-4333-8333-333333333333", "name": "Studio narrator", "previewUrl": "https://files.example.com/saved-narrator.mp3", "source": "clone" }, "cloneUsage": { "canClone": true, "limit": 10, "remaining": 9, "used": 1 } } } } ``` ## 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 | Stato HTTP | Codice | Significato o risoluzione | | - | - | - | | 400 | `CREDENTIAL_IN_QUERY` | Le credenziali sono state fornite in un parametro di query access\_token o api\_key. Invia le credenziali negli header. | | 400 | `IDEMPOTENCY_CONFLICT` | L'intestazione Idempotency-Key e il campo requestId del corpo devono coincidere. | | 400 | `INVALID_REQUEST_ID` | Fornisci requestId o Idempotency-Key come UUID v4. | | 400 | `VALIDATION_ERROR` | L'input non corrisponde allo schema dell'azione; controlla details per gli errori dei campi. | | 400 | `VOICE_CLONE_INVALID_AUDIO` | Un campione caricato non ha una durata audio positiva rilevabile. | | 400 | `VOICE_CLONE_INVALID_FILE_SIZE` | Un campione memorizzato è vuoto o supera 20 MiB. | | 400 | `VOICE_CLONE_INVALID_FILE_TYPE` | Un campione non è audio MP3, WAV, M4A, OGG o Opus. | | 400 | `VOICE_CLONE_SAMPLE_TOO_LONG` | I campioni combinati superano 120 secondi e il ritaglio non è stato abilitato. | | 400 | `VOICE_CLONE_SAMPLE_TOO_SHORT` | I campioni combinati contengono meno di 10 secondi di audio. | | 400 | `VOICE_SAMPLE_NOT_OWNED` | La chiave di un campione non è sicura oppure non appartiene all'account autenticato. | | 401 | `API_KEY_EXPIRED` | La chiave API è scaduta. | | 401 | `INVALID_API_KEY` | Fornisci una chiave API valida e non scaduta. | | 401 | `INVALID_CREDENTIAL` | L'header Authorization non è valido oppure è in conflitto con x-api-key. | | 401 | `MISSING_CREDENTIAL` | Non è stata fornita alcuna credenziale utilizzabile negli header, oppure la credenziale superava 4096 caratteri. | | 401 | `USER_NOT_FOUND` | L'account associato alla credenziale non esiste più. | | 403 | `ACCOUNT_UNAVAILABLE` | L'account che esegue l'azione o quello di fatturazione non è disponibile o è in fase di eliminazione. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | L'utente della credenziale appartiene a più di un team, quindi il contesto di fatturazione è ambiguo. | | 403 | `INSUFFICIENT_SCOPE` | Concedi tutte le autorizzazioni richieste o scegli un'altra credenziale. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Impossibile verificare i limiti di integrazione dell'account. | | 403 | `SUBSCRIPTION_REQUIRED` | Usa un abbonamento a pagamento attivo. | | 403 | `TEAM_OWNER_NOT_FOUND` | Non è stato possibile trovare l'account effettivo del proprietario del team. | | 403 | `VOICE_CLONING_REQUIRES_PAID_PLAN` | Il piano attuale non consente di salvare voci TTS personalizzate. | | 404 | `VOICE_CLONE_NOT_FOUND` | La richiesta di clonazione non appartiene all'account autenticato oppure non è più disponibile. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Questo account ha già 10 azioni di integrazione in esecuzione. Interroga una richiesta esistente prima di avviarne un'altra. | | 409 | `IDEMPOTENCY_CONFLICT` | Riutilizza un identificatore solo con la stessa operazione e gli stessi argomenti. | | 409 | `VOICE_CLONE_IN_PROGRESS` | È ancora in corso la creazione di un clone che usa questo requestId. | | 409 | `VOICE_CLONE_LIMIT_REACHED` | Tutti gli slot per le voci TTS personalizzate salvate sono occupati. | | 409 | `VOICE_CREATION_IN_PROGRESS` | Le modifiche alle voci sono bloccate durante l'eliminazione dell'account. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Attendi il ripristino mensile o cambia piano. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Rispetta Retry-After quando presente e applica attese crescenti tra i tentativi. | | 500 | `INTERNAL_ERROR` | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. | | 502 | `INTERNAL_ERROR` | Non è stato possibile completare l'azione o confermarne l'esito. Esamina lo stato della richiesta e la cronologia della risorsa prima di avviare un'altra generazione. | | 503 | `ACTION_RESULT_UNAVAILABLE` | L'azione è stata eseguita ma non è stato possibile salvarne il risultato. Esamina lo stato della richiesta salvata e la cronologia delle risorse prima di avviare una nuova generazione. | | 503 | `SERVER_RESTARTING` | Il server si sta riavviando. Riprova tra poco e mantieni lo stesso identificatore della richiesta per una modifica. | ```json theme={null} { "code": "INSUFFICIENT_SCOPE", "message": "This credential does not permit the requested action.", "status": 403, "details": { "requiredScopes": ["voices:write"] } } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.