Text-to-Speech (TTS)

Generate AI-powered audio from text using Replicer AI voices, retrieve generation status via polling, and list past generations.

Create a TTS generation

POST /v1/tts

Submit text to be converted into speech. The generation is queued and processed asynchronously. Poll GET /v1/tts/{id} until the status is completed or failed.

Required scope: tts:write

Request body

Field	Type	Required	Description
text	string	Yes	The text to convert to speech (max 10,000 characters)
voice	string	No	Voice ID or name (default: Sarah). See Voices
language	string	No	Language code, e.g. en, it, es (default: en)
speed	number	No	Playback speed, 0.25 – 4.0 (default: 1.0)
stability	number	No	Voice stability, 0 – 1 (default: 0.4)
similarityBoost	number	No	Similarity boost, 0 – 1 (default: 0.75)
style	number	No	Style exaggeration, 0 – 1 (default: 0)

Example

curl -X POST https://api.replicer.ai/v1/tts \
  -H "Authorization: Bearer rpl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! This is a test of the text-to-speech API.",
    "voice": "Aria",
    "language": "en",
    "speed": 1.0,
    "stability": 0.4,
    "similarityBoost": 0.75
  }'

Response 201 Created

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

Errors

Code	Cause
validation_error	Missing text or text exceeds 10,000 characters
internal_error	TTS worker is unavailable

When processing fails, the generation status becomes failed and errorMessage is set. Common values include voice_not_found, insufficient_balance, worker_unavailable, upload_failed, and provider_transient_error.

---

Get a TTS generation

GET /v1/tts/{id}

Retrieve the current status and details of a TTS generation. Use this endpoint to poll for completion.

Required scope: tts:read

Path parameters

Parameter	Type	Description
id	string	The TTS generation ID

Example

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

Response 200 OK

{
  "data": {
    "id": "clx9876543210",
    "text": "Hello! This is a test of the text-to-speech API.",
    "characterCount": 50,
    "voice": "Aria",
    "language": "en",
    "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"
}

Status values

Status	Description
queued	Generation is waiting to be processed
processing	Audio is being generated
completed	Audio is ready — audioUrl is populated
failed	Generation failed — check errorMessage

errorMessage values (failed generations)

Value	Description
voice_not_found	The voice value is not a known alias and is not a valid voice ID in your library
insufficient_balance	Organization token balance is too low
worker_unavailable	TTS worker could not be reached
upload_failed	Audio was generated but could not be stored
provider_transient_error	Temporary provider error — safe to retry
provider_error_*	Permanent provider HTTP error

Polling strategy

Poll GET /v1/tts/{id} every 3–5 seconds until status is completed or failed.

# Poll until completed
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 "Status: $STATUS"
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] && break
  sleep 3
done

Errors

Code	Cause
not_found	Generation doesn't exist or doesn't belong to your org

---

List TTS generations

GET /v1/tts

Retrieve a paginated list of TTS generations for your organization.

Required scope: tts:read

Query parameters

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Results per page (max 100)
status	string	—	Filter by status: queued, processing, completed, failed

Example

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

Response 200 OK

{
  "data": [
    {
      "id": "clx9876543210",
      "text": "Hello! This is a test.",
      "characterCount": 23,
      "voice": "Aria",
      "language": "en",
      "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"
}

---

Voices

The following built-in voices are available. You can also pass any supported voice ID (20-character alphanumeric) from your voice library.

Standard voices (English)

Female

ID	Name	Description
Aria	Aria	Clear, natural voice
Sarah	Sarah	Mature, reassuring
Rachel	Rachel	Warm, calm voice
Arabella	Arabella	Mysterious, emotive
Hope	Hope	Bright, conversational
Alexandra	Alexandra	Confident, conversational
Priyanka	Priyanka	Late-night radio cadence
Monika	Monika	Multilingual, popular
Juniper	Juniper	Grounded professional
Blondie	Blondie	Conversational variant
Domi	Domi	Strong, dynamic

Male

ID	Name	Description
Roger	Roger	Confident narrator
Grimblewood	Grimblewood	Deep, characterful
Drew	Drew	Casual, relatable
Paul	Paul	Steady, trustworthy
Clyde	Clyde	Gruff, characterful
Dave	Dave	Friendly, approachable
Fin	Fin	Crisp, clear
James	James	Husky, engaging
Bradford	Bradford	Expressive, articulate
Reginald	Reginald	Intense, villain
Mark	Mark	Conversational
Austin	Austin	Southern American gentleman

Custom voices (Italian)

ID	Name	Accent	Description
Lorenzo	Lorenzo	Italiano	Youthful modern pro voice
Roberta	Roberta	Romanesco	Persuasive young voice
Sasha	Sasha	Toscano	Natural, layered Tuscan
Giusy	Giusy	Siciliano	Sales / customer support
Vera	Vera	Milanese	Calm, influential conversational
Vittorio	Vittorio	Milanese	Believable guy-next-door

Custom voice IDs

Integrators may pass a raw voice ID (20-character alphanumeric) in the voice field instead of a built-in alias. The ID must exist in your organization's voice library.

---

Billing

TTS generations consume tokens from your organization balance:

Characters	Token cost
1 – 100	10 tokens
101 – 200	20 tokens
201 – 300	30 tokens
...	10 tokens per 100 chars (rounded up)
1,000	100 tokens
5,000	500 tokens

Tokens are deducted when processing begins. If the generation fails, tokens are automatically refunded.