Text-to-Speech (TTS)

Genera audio tramite AI a partire da testo, usando le voci ElevenLabs. 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: Aria). 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.5)
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.5,
    "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

---

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.5,
    "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

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.5,
      "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 sono disponibili. Puoi anche usare qualsiasi ID voce ElevenLabs direttamente.

Voci femminili

ID	Nome	Descrizione
Aria	Aria	Voce chiara, naturale
Sarah	Sarah	Amichevole, colloquiale
Rachel	Rachel	Calda, tranquilla
Jane	Jane	Professionale, curata
Arabella	Arabella	Elegante, raffinata
Hope	Hope	Morbida, gentile
Alexandra	Alexandra	Sicura, chiara
Priyanka	Priyanka	Calda, espressiva
Monika	Monika	Fluida, articolata
Juniper	Juniper	Brillante, giovanile
Blondie	Blondie	Vivace, energica
Domi	Domi	Forte, dinamica

Voci maschili

ID	Nome	Descrizione
Roger	Roger	Narratore professionale
Grimblewood	Grimblewood	Profonda, calda
Drew	Drew	Informale, coinvolgente
Paul	Paul	Stabile, affidabile
Clyde	Clyde	Ruvida, caratteristica
Dave	Dave	Amichevole, accessibile
Fin	Fin	Nitida, chiara
James	James	Autorevole, profonda
Bradford	Bradford	Distinta, formale
Reginald	Reginald	Classica, raffinata
Mark	Mark	Neutra, versatile
Austin	Austin	Energica, giovanile
Kuon	Kuon	Calma, fluida
Gaming	Gaming	Vivace, dinamica

ID voce personalizzati

Puoi usare qualsiasi ID voce ElevenLabs valido nel campo voice. I nomi sopra elencati sono scorciatoie per comodità.

---

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.