Text-to-Speech (TTS)

Genera audio tramite AI a partire da testo, usando le voci Replicer AI. Controlla lo stato della generazione con il polling e visualizza lo storico.

Creare una generazione TTS

POST /v1/tts

Invia un testo da convertire in audio. La generazione viene messa in coda ed elaborata in modo asincrono. Usa GET /v1/tts/{id} per il polling fino a quando lo stato è completed o failed.

Scope richiesto: tts:write

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
text	string	Sì	Il testo da convertire in audio (max 10.000 caratteri)
voice	string	No	ID o nome della voce (default: Sarah). Vedi Voci
language	string	No	Codice lingua, es. en, it, es (default: en)
speed	number	No	Velocità di riproduzione, 0.25 – 4.0 (default: 1.0)
stability	number	No	Stabilità della voce, 0 – 1 (default: 0.4)
similarityBoost	number	No	Boost similarità, 0 – 1 (default: 0.75)
style	number	No	Esagerazione stile, 0 – 1 (default: 0)

Esempio

curl -X POST https://api.replicer.ai/v1/tts \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Ciao! Questo è un test dell API text-to-speech.",
    "voice": "Aria",
    "language": "it",
    "speed": 1.0,
    "stability": 0.4,
    "similarityBoost": 0.75
  }'

Risposta 201 Created

{
  "data": {
    "id": "clx9876543210",
    "status": "queued",
    "characterCount": 50
  },
  "requestId": "req-abc123"
}

Errori

Codice	Causa
validation_error	text mancante o superiore a 10.000 caratteri
internal_error	Worker TTS non disponibile

Quando l'elaborazione fallisce, lo status diventa failed e errorMessage viene impostato. Valori comuni: voice_not_found, insufficient_balance, worker_unavailable, upload_failed, provider_transient_error.

---

Ottenere una generazione TTS

GET /v1/tts/{id}

Recupera lo stato e i dettagli di una generazione TTS. Usa questo endpoint per il polling fino al completamento.

Scope richiesto: tts:read

Parametri path

Parametro	Tipo	Descrizione
id	string	L'ID della generazione TTS

Esempio

curl https://api.replicer.ai/v1/tts/clx9876543210 \
  -H "Authorization: Bearer rpl_live_your_key"

Risposta 200 OK

{
  "data": {
    "id": "clx9876543210",
    "text": "Ciao! Questo è un test dell API text-to-speech.",
    "characterCount": 50,
    "voice": "Aria",
    "language": "it",
    "speed": 1.0,
    "stability": 0.4,
    "similarityBoost": 0.75,
    "style": 0,
    "source": "api",
    "status": "completed",
    "audioUrl": "https://pub-xxx.r2.dev/tts/org123/clx9876543210.mp3",
    "tokenCost": 100,
    "createdAt": "2026-04-07T10:00:00.000Z",
    "completedAt": "2026-04-07T10:00:05.000Z"
  },
  "requestId": "req-def456"
}

Valori dello stato

Stato	Descrizione
queued	In attesa di elaborazione
processing	Audio in fase di generazione
completed	Audio pronto — audioUrl disponibile
failed	Generazione fallita — controlla errorMessage

Valori di errorMessage (generazioni fallite)

Valore	Descrizione
voice_not_found	Il valore voice non è un alias noto e non è un ID voce valido nella tua libreria
insufficient_balance	Saldo token dell'organizzazione insufficiente
worker_unavailable	Worker TTS non raggiungibile
upload_failed	Audio generato ma non salvato
provider_transient_error	Errore temporaneo del provider — riprova
provider_error_*	Errore HTTP permanente del provider

Strategia di polling

Interroga GET /v1/tts/{id} ogni 3–5 secondi fino a quando status è completed o failed.

# Polling fino al completamento
while true; do
  STATUS=$(curl -s https://api.replicer.ai/v1/tts/clx9876543210 \
    -H "Authorization: Bearer rpl_live_your_key" | jq -r '.data.status')
  echo "Stato: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 3
done

Errori

Codice	Causa
not_found	Generazione non trovata o non appartiene alla tua organizzazione

---

Elenco generazioni TTS

GET /v1/tts

Recupera un elenco paginato delle generazioni TTS della tua organizzazione.

Scope richiesto: tts:read

Parametri query

Parametro	Tipo	Default	Descrizione
page	integer	1	Numero di pagina
limit	integer	20	Risultati per pagina (max 100)
status	string	—	Filtra per stato: queued, processing, completed, failed

Esempio

curl "https://api.replicer.ai/v1/tts?page=1&limit=10&status=completed" \
  -H "Authorization: Bearer rpl_live_your_key"

Risposta 200 OK

{
  "data": [
    {
      "id": "clx9876543210",
      "text": "Ciao! Questo è un test.",
      "characterCount": 23,
      "voice": "Aria",
      "language": "it",
      "speed": 1.0,
      "stability": 0.4,
      "similarityBoost": 0.75,
      "style": 0,
      "source": "api",
      "status": "completed",
      "audioUrl": "https://pub-xxx.r2.dev/tts/org123/clx9876543210.mp3",
      "tokenCost": 100,
      "createdAt": "2026-04-07T10:00:00.000Z",
      "completedAt": "2026-04-07T10:00:05.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  },
  "requestId": "req-ghi789"
}

---

Voci

Le seguenti voci integrate sono disponibili. Puoi anche passare un ID voce supportato (20 caratteri alfanumerici) dalla tua libreria voci.

Voci standard (inglese)

Femminili

ID	Nome	Descrizione
Aria	Aria	Voce chiara, naturale
Sarah	Sarah	Maturo, rassicurante
Rachel	Rachel	Calda, tranquilla
Arabella	Arabella	Misteriosa, emotiva
Hope	Hope	Brillante, colloquiale
Alexandra	Alexandra	Sicura, colloquiale
Priyanka	Priyanka	Cadenza radio notturna
Monika	Monika	Multilingue, popolare
Juniper	Juniper	Professionale, concreta
Blondie	Blondie	Variante colloquiale
Domi	Domi	Forte, dinamica

Maschili

ID	Nome	Descrizione
Roger	Roger	Narratore sicuro
Grimblewood	Grimblewood	Profonda, caratteristica
Drew	Drew	Informale, coinvolgente
Paul	Paul	Stabile, affidabile
Clyde	Clyde	Ruvida, caratteristica
Dave	Dave	Amichevole, accessibile
Fin	Fin	Nitida, chiara
James	James	Rauca, coinvolgente
Bradford	Bradford	Espressiva, articolata
Reginald	Reginald	Intensa, antagonista
Mark	Mark	Colloquiale
Austin	Austin	Gentiluomo del sud USA

Voci personalizzate (italiano)

ID	Nome	Accento	Descrizione
Lorenzo	Lorenzo	Italiano	Voce giovane e moderna
Roberta	Roberta	Romanesco	Voce giovane persuasiva
Sasha	Sasha	Toscano	Toscano naturale e stratificato
Giusy	Giusy	Siciliano	Vendite / assistenza clienti
Vera	Vera	Milanese	Colloquiale calma e influente
Vittorio	Vittorio	Milanese	Ragazzo della porta accanto

ID voce personalizzati

Gli integratori possono passare un ID voce grezzo (20 caratteri alfanumerici) nel campo voice al posto di un alias integrato. L'ID deve esistere nella libreria voci della tua organizzazione.

---

Fatturazione

Le generazioni TTS consumano token dal saldo della tua organizzazione:

Caratteri	Costo in token
1 – 100	10 token
101 – 200	20 token
201 – 300	30 token
...	10 token ogni 100 caratteri (arrotondato per eccesso)
1.000	100 token
5.000	500 token

I token vengono detratti quando l'elaborazione inizia. In caso di errore, i token vengono rimborsati automaticamente.