> ## 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.
# Crea l'anteprima di una voce clonata
> Crea un'anteprima temporanea di voce clonata da 1–3 file audio caricati di tua proprietà, con autorizzazione esplicita. Si applica la quota di prova della clonazione dell'app. Salva l'anteprima selezionata prima della scadenza per conservarla.
Crea un'anteprima temporanea di voce clonata da 1–3 file audio caricati di tua proprietà, con autorizzazione esplicita. Si applica la quota di prova della clonazione dell'app. Salva l'anteprima selezionata prima della scadenza per conservarla.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/voices_preview_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_preview_clone' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","name":"Studio narrator","samples":[{"fileKey":"uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}],"hasPermission":true,"trimToMaxDuration":false,"language":"en"}'
```
```javascript JavaScript theme={null}
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
name: 'Studio narrator',
samples: [
{
fileKey: 'uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav',
},
],
hasPermission: true,
trimToMaxDuration: false,
language: 'en',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_preview_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_preview_clone",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "name": "Studio narrator", "samples": [{"fileKey": "uploads/example-user/66666666-6666-4666-8666-666666666666-narrator.wav"}], "hasPermission": True, "trimToMaxDuration": False, "language": "en"},
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.
Tutte le anteprime vocali attive non salvate e le quote di creazione aggiornate, incluso il nuovo candidato di clonazione.
```json HTTP 202 theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```
```json HTTP 200 theme={null}
{
"data": {
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_preview_clone",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_preview_clone",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```
## Campi del risultato
| Campo | Descrizione |
| - | - |
| `data.voicePreviews` | Tutte le anteprime attualmente attive e non salvate per questo account, inclusi i candidati di richieste precedenti. |
| `data.voicePreviews[].id` | UUID v4 dell'anteprima utilizzato da voices\_preview\_get e voices\_save\_preview. |
| `data.voicePreviews[].kind` | clone o design. |
| `data.voicePreviews[].name` | Nome visualizzato dell'anteprima; i candidati progettati aggiungono un numero al nome richiesto. |
| `data.voicePreviews[].previewUrl` | URL audio temporaneo riproducibile. Richiedi un nuovo URL con voices\_preview\_get finché l'anteprima rimane attiva. |
| `data.voicePreviews[].expiresAt` | Scadenza dell'anteprima come timestamp Unix in millisecondi. |
| `data.voicePreviews[].durationSeconds` | Durata dell'audio di anteprima in secondi. |
| `data.creationUsage.cloneTrial` | Quota di prova dell'anteprima di clonazione valida per l'intera durata dell'account, con limit, used e remaining. |
| `data.creationUsage.design` | Quota giornaliera di progettazione vocale con limit, used, remaining e resetsAt in millisecondi Unix. |
| `data.creationUsage.previewExpiresAfterHours` | Durata di validità di un'anteprima non salvata in ore, attualmente 24. |
## 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":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"voices_preview_clone"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "voices_preview_clone",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"voicePreviews": [
{
"id": "44444444-4444-4444-8444-444444444444",
"kind": "clone",
"name": "Studio narrator",
"previewUrl": "https://files.example.com/narrator-preview.mp3",
"expiresAt": 1792238400000,
"durationSeconds": 10
}
],
"creationUsage": {
"cloneTrial": {
"limit": 1,
"used": 1,
"remaining": 0
},
"design": {
"limit": 5,
"used": 0,
"remaining": 5,
"resetsAt": 1792195200000
},
"previewExpiresAfterHours": 24
}
}
}
}
```
## 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.
* Usa l'unica prova di anteprima di clonazione disponibile per tutta la durata dell'account. La creazione di questa anteprima non salva una voce TTS riutilizzabile né occupa uno slot di voce salvata.
* Il nuovo candidato di clonazione ha kind: clone e dura 24 ore. La sua riproduzione è limitata a circa 10 secondi.
* La risposta include tutte le anteprime attive non salvate. Usa voices\_preview\_get per aggiornare la riproduzione, quindi voices\_save\_preview per conservare il candidato scelto con un piano a pagamento.
* language sceglie il testo dell'anteprima quando esiste un testo supportato; non è una richiesta di traduzione del campione caricato.
* 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. |
| 404 | `USER_NOT_FOUND` | L'account autenticato non esiste più. |
| 404 | `VOICE_PREVIEW_NOT_FOUND` | La richiesta appartiene a un altro account. |
| 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_CREATION_IN_PROGRESS` | La creazione dell'anteprima è ancora in corso oppure l'eliminazione dell'account blocca nuove operazioni sulle voci. |
| 409 | `VOICE_CREATION_REQUEST_MISMATCH` | Questo requestId è stato usato per un tipo di voce, impostazioni o campioni diversi. |
| 409 | `VOICE_TRIAL_LIMIT_REACHED` | L'account ha già utilizzato la prova di anteprima della clonazione disponibile una sola volta. |
| 410 | `VOICE_PREVIEW_EXPIRED` | L'anteprima vocale della richiesta è scaduta oppure non è più disponibile. |
| 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.