Text-to-Speech (TTS)

Generate AI-powered audio from text using ElevenLabs 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: Aria). 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.5)
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.5,
    "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

---

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.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"
}

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

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.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"
}

---

Voices

The following built-in voices are available. You can also use any ElevenLabs voice ID directly.

Female voices

ID	Name	Description
Aria	Aria	Clear, natural voice
Sarah	Sarah	Friendly, conversational
Rachel	Rachel	Warm, calm voice
Jane	Jane	Professional, polished
Arabella	Arabella	Elegant, refined
Hope	Hope	Soft, gentle
Alexandra	Alexandra	Confident, clear
Priyanka	Priyanka	Warm, expressive
Monika	Monika	Smooth, articulate
Juniper	Juniper	Bright, youthful
Blondie	Blondie	Lively, energetic
Domi	Domi	Strong, dynamic

Male voices

ID	Name	Description
Roger	Roger	Professional narrator
Grimblewood	Grimblewood	Deep, warm voice
Drew	Drew	Casual, relatable
Paul	Paul	Steady, trustworthy
Clyde	Clyde	Gruff, characterful
Dave	Dave	Friendly, approachable
Fin	Fin	Crisp, clear
James	James	Authoritative, deep
Bradford	Bradford	Distinguished, formal
Reginald	Reginald	Classic, refined
Mark	Mark	Neutral, versatile
Austin	Austin	Energetic, youthful
Kuon	Kuon	Calm, smooth
Gaming	Gaming	Upbeat, dynamic

Custom voice IDs

You can use any valid ElevenLabs voice ID in the voice field. The built-in names above are shortcuts for convenience.

---

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.