> ## 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.

# Salva un'anteprima vocale

> Salva un'anteprima di voce clonata o progettata di tua proprietà e non scaduta come voce riutilizzabile. I salvataggi ripetuti della stessa anteprima riutilizzano la voce salvata.

Salva un'anteprima di voce clonata o progettata di tua proprietà e non scaduta come voce riutilizzabile. I salvataggi ripetuti della stessa anteprima riutilizzano la voce salvata.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/voices_save_preview
```

## Autenticazione e autorizzazioni

<ParamField header="x-api-key" type="string" required>
  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.
</ParamField>

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

<ParamField body="requestId" type="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}$`.
</ParamField>

<ParamField body="previewId" type="string" required>
  Valore testuale.

  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})$`.
</ParamField>

<ParamField body="name" type="string" required>
  Valore testuale.

  Lunghezza minima: 1. Lunghezza massima: 80.
</ParamField>

<Accordion title="Schema di input completo">
  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}$"
      },
      "previewId": {
        "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
      }
    },
    "required": ["previewId", "name"],
    "additionalProperties": false
  }
  ```
</Accordion>

## 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.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST 'https://api.voicecheap.ai/v1/actions/voices_save_preview' \
    --header "x-api-key: $VOICECHEAP_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","previewId":"44444444-4444-4444-8444-444444444444","name":"Studio narrator"}'
  ```

  ```javascript JavaScript theme={null}
  const input = {
    requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
    previewId: '44444444-4444-4444-8444-444444444444',
    name: 'Studio narrator',
  };
  const response = await fetch('https://api.voicecheap.ai/v1/actions/voices_save_preview', {
    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_save_preview",
      headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
      json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "previewId": "44444444-4444-4444-8444-444444444444", "name": "Studio narrator"},
      timeout=120,
  )
  body = response.json()
  if not response.ok:
      raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
  print(body)
  ```
</RequestExample>

## 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 riutilizzabile salvata, la disponibilità aggiornata degli slot di salvataggio, le anteprime attive non salvate rimanenti e le quote di creazione rimanenti.

<ResponseExample>
  ```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": [],
      "creationUsage": {
        "cloneTrial": {
          "limit": 1,
          "used": 1,
          "remaining": 0
        },
        "design": {
          "limit": 5,
          "used": 0,
          "remaining": 5,
          "resetsAt": 1792195200000
        },
        "previewExpiresAfterHours": 24
      },
      "voice": {
        "accent": "original",
        "id": "clone:44444444-4444-4444-8444-444444444444",
        "name": "Studio narrator",
        "previewUrl": "https://files.example.com/saved-narrator.mp3",
        "source": "clone"
      },
      "cloneUsage": {
        "canClone": true,
        "limit": 10,
        "remaining": 9,
        "used": 1
      }
    },
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
  }
  ```

  ```json HTTP 202 replay_running theme={null}
  {
    "data": {
      "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
      "operation": "voices_save_preview",
      "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_save_preview",
      "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"
  }
  ```
</ResponseExample>

## 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. |
| `data.voice.id` | ID di selezione TTS riutilizzabile clone:\<UUID>. 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":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"voices_save_preview"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "voices_save_preview",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "voicePreviews": [],
      "creationUsage": {
        "cloneTrial": {
          "limit": 1,
          "used": 1,
          "remaining": 0
        },
        "design": {
          "limit": 5,
          "used": 0,
          "remaining": 5,
          "resetsAt": 1792195200000
        },
        "previewExpiresAfterHours": 24
      },
      "voice": {
        "accent": "original",
        "id": "clone:44444444-4444-4444-8444-444444444444",
        "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.
* previewId è l'UUID del candidato di proprietà dell'utente restituito da voices\_preview\_clone o voices\_design. name contiene 1–80 caratteri dopo la rimozione degli spazi iniziali e finali.
* Il salvataggio richiede un piano a pagamento, uno slot disponibile per una voce TTS salvata e un'anteprima non scaduta nello stato ready. Questa azione funziona per candidati clonati e progettati.
* L'ID di selezione riutilizzabile è clone:\<previewId>. Un candidato salvato scompare da voicePreviews; voices\_list lo include tra le voci salvate.
* I salvataggi ripetuti dello stesso candidato già salvato riutilizzano la voce salvata. Il nome originale salvato viene mantenuto nei salvataggi successivi.
* voice può essere omesso se la voce salvata non è presente nell'elenco delle voci aggiornato. Recupera le voci salvate attuali tramite voices\_list.
* 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. |
| 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 corrente non consente di salvare e riutilizzare voci TTS personalizzate. |
| 404 | `USER_NOT_FOUND` | L'account autenticato non esiste più. |
| 404 | `VOICE_PREVIEW_NOT_FOUND` | L'anteprima è assente oppure 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_CLONE_LIMIT_REACHED` | Tutti gli slot per le voci TTS personalizzate salvate sono occupati. |
| 409 | `VOICE_CREATION_IN_PROGRESS` | Il salvataggio di questo candidato è ancora in corso oppure l'eliminazione dell'account blocca nuove operazioni sulle voci. |
| 410 | `VOICE_PREVIEW_EXPIRED` | Il candidato è scaduto, non è nello stato ready oppure non dispone più di audio di anteprima utilizzabile. |
| 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.