POST/api/v6/tts/synthesize

Synthesize text to speech

Turns a text into audio and returns its reference. Synchronous.

Scope

API key with the tts service enabled

Usage limit

60 requests per minute

Idempotency

Supports Idempotency-Key

Up to 4000 characters of text per request.
Audio lifetime ranges from 1 hour to 1 year; the default is 30 days.

Turns a text into an audio file and returns its reference. Synthesis is synchronous: the response arrives once the audio is ready.

The voice is chosen with voice, using a code from the catalog (see GET /api/v6/tts/voices). Text allows up to 4000 characters per request.

The same text with the same voice is reused automatically: if you already generated that audio, the response arrives with cached: true and without processing it again.

Request body

application/json

text

stringrequired

Text to synthesize. Between 1 and 4000 characters.

voice

stringrequired

Voice code from the catalog (see GET /api/v6/tts/voices).

speakingRate

numberoptional

Speaking rate, from 0.25 to 4.0. Defaults to 1.0.

Default: 1

format

stringoptional

Audio format. Only wav for now.

wav

ttlSeconds

integeroptional

Audio lifetime in seconds (minimum 1 hour, maximum 1 year). Set when the audio is created; reusing an already-generated audio keeps its original lifetime.

Default: 2592000

{
  "text": "Hola, te llamamos de Acme para confirmar tu cita.",
  "voice": "es-us-female-2",
  "speakingRate": 1
}

Responses

201

Audio ready, freshly generated or reused.

{
  "success": true,
  "data": {
    "id": "01J9Z4M7K2QABCDEF5GHTV3WXY",
    "status": "completed",
    "cached": false,
    "charCount": 49,
    "durationMs": 3120,
    "voice": "es-us-female-2",
    "cost": "12.500000",
    "currency": "COP",
    "audioUrl": "https://storage.hablame.co/tts/9f2c...e1.wav?Expires=...&Signature=..."
  },
  "meta": {
    "requestId": "8f0c0e2a4b1d4c8fae2b7a91e0c5d3f6",
    "timestamp": "2026-06-23T15:04:05+00:00",
    "responseTimeMs": 412.5
  }
}

400

Invalid input: empty or too long text, unknown voice, or an out-of-range parameter.

401

Invalid or missing credentials.

402

Insufficient balance to generate the audio.

403

The API key does not have the tts service enabled, or a spending limit prevents generation.

429

Request limit exceeded.

Possible errors

Codes this endpoint can return in error.code. The full detail lives in the catalog.

401AUTH_REQUIREDNo Bearer token was sent, and every call requires one.401AUTH_INVALID_KEYThe API key is not recognized: wrong format, revoked or expired.401AUTH_SERVICE_NOT_ALLOWEDThe key is not allowed to use the service behind this endpoint.400BAD_REQUESTWe could not parse your request.403ACCOUNT_READ_ONLYRead-only mode: only GET, HEAD and OPTIONS pass.429RATE_TPS_EXCEEDEDYou exceeded your organization quota for this endpoint.

See the full catalog

Scope and limits

Request body

Responses

Possible errors