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

# Genera la voce

> Crea la voce dal testo usando una voce del catalogo o una voce personalizzata di tua proprietà. Si applicano gli stessi crediti di caratteri e limiti del piano dell'app. Restituisce un ID di cronologia e un URL di download audio temporaneo. Riutilizza requestId per evitare una seconda generazione.

Crea la voce dal testo usando una voce del catalogo o una voce personalizzata di tua proprietà. Si applicano gli stessi crediti di caratteri e limiti del piano dell'app. Restituisce un ID di cronologia e un URL di download audio temporaneo. Riutilizza requestId per evitare una seconda generazione.

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

## Autenticazione e autorizzazioni

**x-api-key** `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.

Autorizzazioni richieste: `tts: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

**requestId** `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}$`.

**text** `string` *required*

Valore testuale.

Lunghezza minima: 1. Lunghezza massima: 128000.

**voice** `string` *required*

Un ID di selezione della voce da voices\_list, inclusi gli ID clone: per le voci personalizzate salvate.

Lunghezza minima: 1. Lunghezza massima: 255.

**inputType** `string`

Valore testuale.

Valori consentiti: "text", "pdf". Valore predefinito: "text".

**instructionPreset** `string`

Valore testuale.

Valori consentiti: "default", "cheerful", "calm", "narrator", "dramatic", "whisper", "energetic". Valore predefinito: "default".

**instructions** `string`

Valore testuale.

Lunghezza massima: 300.

**speed** `number`

Valore numerico.

Minimo: 0.5. Massimo: 2. Valore predefinito: 1.

**sourceFileName** `string`

Valore testuale.

Lunghezza massima: 255.

> [accordion] 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}$"
>     },
>     "text": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 128000
>     },
>     "voice": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 255,
>       "description": "A voice selection ID from voices_list, including clone: IDs for saved custom voices."
>     },
>     "inputType": {
>       "default": "text",
>       "type": "string",
>       "enum": ["text", "pdf"]
>     },
>     "instructionPreset": {
>       "default": "default",
>       "type": "string",
>       "enum": ["default", "cheerful", "calm", "narrator", "dramatic", "whisper", "energetic"]
>     },
>     "instructions": {
>       "type": "string",
>       "maxLength": 300
>     },
>     "speed": {
>       "default": 1,
>       "type": "number",
>       "minimum": 0.5,
>       "maximum": 2
>     },
>     "sourceFileName": {
>       "type": "string",
>       "maxLength": 255
>     }
>   },
>   "required": ["text", "voice"],
>   "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/tts_generate' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","text":"Hello world.","voice":"933563129e564b19a115bedd57b7406a","inputType":"text","instructionPreset":"narrator","instructions":"Speak clearly and leave a short pause at the end.","speed":1,"sourceFileName":"launch-script.txt"}'
```

```javascript JavaScript theme={null}
const input = {
  requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
  text: 'Hello world.',
  voice: '933563129e564b19a115bedd57b7406a',
  inputType: 'text',
  instructionPreset: 'narrator',
  instructions: 'Speak clearly and leave a short pause at the end.',
  speed: 1,
  sourceFileName: 'launch-script.txt',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_generate', {
  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/tts_generate",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "text": "Hello world.", "voice": "933563129e564b19a115bedd57b7406a", "inputType": "text", "instructionPreset": "narrator", "instructions": "Speak clearly and leave a short pause at the end.", "speed": 1, "sourceFileName": "launch-script.txt"},
    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.

Metadati della generazione vocale completata e un URL temporaneo di download MP3. Il gestore non restituisce byte audio.

```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": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
    "status": "completed",
    "characterCount": 12,
    "previewEndIndex": null,
    "downloadUrl": "https://files.example.com/launch-script-speech.mp3"
  },
  "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
```

```json HTTP 202 replay_running theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "tts_generate",
    "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": "tts_generate",
    "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.requestId` | UUID v4 fornito per l'azione di generazione. |
| `data.historyId` | ID della cronologia vocale di proprietà dell'utente: 64 caratteri esadecimali minuscoli, con prefisso facoltativo free- per un'anteprima dell'app. |
| `data.status` | completed quando il risultato vocale è pronto. |
| `data.characterCount` | Numero di caratteri nell'intero testo di input dopo la rimozione degli spazi iniziali e finali. |
| `data.previewEndIndex` | Limite in caratteri dell'audio di anteprima parziale, oppure null per l'audio completo. La generazione tramite integrazione a pagamento restituisce l'audio completo. |
| `data.downloadUrl` | URL temporaneo per il download dell'MP3. Richiedine uno nuovo tramite tts\_download. |

## 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":"tts_generate"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
    "operation": "tts_generate",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
      "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d",
      "status": "completed",
      "characterCount": 12,
      "previewEndIndex": null,
      "downloadUrl": "https://files.example.com/launch-script-speech.mp3"
    }
  }
}
```

## 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.
* Scegli voice da voices\_list. Gli ID delle voci di doppiaggio provenienti da dubbing\_voices\_list appartengono a una libreria separata.
* Gli spazi iniziali e finali del testo vengono rimossi. Lo schema accetta al massimo 128,000 caratteri; gli attuali piani Beginner e Starter consentono 64,000 caratteri per generazione, mentre Creator e i piani superiori ne consentono 128,000. Il piano corrente e i crediti disponibili per i caratteri TTS vengono verificati nuovamente prima della generazione.
* inputType ha come valore predefinito text e può essere text o pdf. Anche con pdf, fornisci il testo estratto in text; questa azione non accetta il caricamento o l'URL di un PDF.
* instructionPreset ha come valore predefinito default e supporta default, cheerful, calm, narrator, dramatic, whisper ed energetic. instructions è facoltativo ed è limitato a 300 caratteri senza spazi iniziali e finali. speed ha come valore predefinito 1 e varia da 0.5 a 2.
* sourceFileName è un metadato facoltativo, limitato a 255 caratteri dopo la rimozione degli spazi iniziali e finali, e determina il nome del file di download.
* Una richiesta ripetuta riuscita riproduce l'audio salvato senza generarlo né addebitarlo di nuovo. Gli URL sono temporanei; usa tts\_download per un nuovo download.
* 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 | `INVALID_VOICE` | La selezione della voce non è valida, non è di proprietà di questo account oppure non è in stato ready. |
| 400 | `TEXT_REQUIRED` | Il testo è vuoto dopo la rimozione dei tag di controllo dell'interpretazione vocale. |
| 400 | `TEXT_TOO_LONG` | Il testo supera il limite di caratteri per generazione del piano corrente. |
| 400 | `VALIDATION_ERROR` | L'input non corrisponde allo schema dell'azione; controlla details per gli errori dei campi. |
| 400 | `VOICE_UNAVAILABLE` | La voce del catalogo selezionata non è più disponibile; scegli un ID restituito da voices\_list. |
| 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 | `PAID_PLAN_REQUIRED` | L'account attuale non dispone più di un piano a pagamento per la generazione vocale tramite integrazione. |
| 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. |
| 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 | `TEXT_TO_SPEECH_GENERATION_IN_PROGRESS` | Una richiesta vocale identica è ancora in elaborazione. |
| 409 | `TEXT_TO_SPEECH_REQUEST_CONFLICT` | Questo requestId è già stato utilizzato con un input vocale diverso. |
| 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. |
| 429 | `TEXT_TO_SPEECH_CHARACTER_LIMIT_REACHED` | Il copione supera il totale dei caratteri TTS inclusi e acquistati disponibili. |
| 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": ["tts:write"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.