canonical: https://jentic.com/apis/ibm.com/text-to-speech

# IBM Watson Text to Speech

Jentic publishes the only available OpenAPI specification for IBM Watson Text to Speech, keeping it validated and agent-ready. IBM Watson Text to Speech synthesises text into natural-sounding audio across multiple languages, dialects, and named voices, and is widely used to add spoken output to IVR systems, accessibility features, and assistants. The API exposes the synthesis endpoint, the catalogue of available voices, a pronunciation lookup, and a customizations resource for managing per-tenant pronunciation overrides.

## For AI agents

Synthesise text into spoken audio in many languages and voices via IBM Watson - list voices, fetch pronunciations, and manage custom pronunciation models.

## Scope

Does not handle speech-to-text, real-time call streaming, or natural language understanding - use for synthesising text into audio with IBM Watson voices only.

## Capabilities

- Synthesise text into audio via `/v1/synthesize`
- List the catalogue of available voices via `/v1/voices`
- Get the details of a specific voice via `/v1/voices/{voice}`
- Look up the phonetic pronunciation of a word via `/v1/pronunciation`
- Manage tenant-level pronunciation customizations via `/v1/customizations`

## Use cases

### IVR Prompt Generation

Render IVR prompts as audio at deploy time or on demand by POSTing the prompt text to `/v1/synthesize` and storing the returned audio. Watson supports multiple languages and named voices, so the same pipeline can produce localised prompts without a voice actor and without redeploying the IVR system.

Example prompt: POST the text 'Press one for billing' to `/v1/synthesize` with voice en-US_AllisonV3Voice and accept audio/mp3, then save the binary response as billing.mp3.

### Accessibility Read-Aloud

Add a spoken read-aloud feature to a web or mobile app by sending the visible text to `/v1/synthesize` and streaming the returned audio to the client. Watson handles the speech generation and a list of voices is available via `/v1/voices`, which lets users pick a preferred voice and language.

Example prompt: Synthesise the body of an article via `/v1/synthesize` using the user's selected voice from `/v1/voices` and stream the audio to the browser.

### Custom Pronunciation Models

Create a customization under `/v1/customizations` to teach Watson how to pronounce industry-specific terms, brand names, or product SKUs. Once a customization is in place, calls to `/v1/synthesize` can reference it so the synthesised audio uses the corrected pronunciation.

Example prompt: Create a customization for the en-US base model, add an entry mapping the brand name 'Acme' to its phonetic spelling, and synthesise a sentence that uses it.

### AI Agent Voice Output

An AI agent uses Jentic to add a spoken-output channel - for example, generating audio briefings or accessibility output - without managing an IBM Cloud IAM token directly. The agent searches by intent, loads the synthesise schema, and posts the text. Typical agent integration is under one hour because the synthesise surface is one operation.

Example prompt: Search Jentic for 'synthesise text to speech with IBM Watson', load the `/v1/synthesize` schema, and produce an MP3 of the daily briefing text.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/synthesize` | Synthesise text into audio |
| GET | `/v1/voices` | List available voices |
| GET | `/v1/voices/{voice}` | Get details of a specific voice |
| GET | `/v1/pronunciation` | Get the pronunciation of a word |
| GET | `/v1/customizations` | List custom pronunciation models |

## Key resources

- **Synthesize** — Convert text to audio in a chosen voice and format
- **Voices** — List available voices and their attributes
- **Pronunciation** — Look up the phonetic spelling of a word
- **Customizations** — Manage per-tenant pronunciation models

## Why Jentic

- **Setup:** Wiring IBM Watson Text to Speech by hand means handling its bearer-token auth against the regional watson.cloud.ibm.com host and shaping each synthesis request yourself. Through Jentic you install once, import IBM Watson Text to Speech from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Watson Text to Speech takes the text and voice in the request and query rather than a resource path, so limit the agent to the operations it needs, such as synthesising audio and listing voices. You choose that allowed set, so an agent scoped to synthesis and voice reads cannot touch custom voice models unless you add those operations.
- **Credential handling:** Your Watson Text to Speech token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert text to speech' or 'list available Watson voices', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ElevenLabs API** — ElevenLabs offers state-of-the-art neural voice cloning and synthesis; Watson focuses on enterprise-grade multilingual TTS.
- **OpenAI API** — OpenAI's audio endpoints provide TTS alongside chat and whisper; Watson is a dedicated speech service.
- **Deepgram API** — Deepgram is a speech-to-text service that pairs with Watson TTS to build a full conversational stack.

## FAQ

### Why is there no official OpenAPI spec for IBM Watson Text to Speech?

IBM does not publish an OpenAPI specification for Watson Text to Speech. Jentic generates and maintains this spec so that AI agents and developers can call IBM Watson Text to Speech via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the IBM Watson Text to Speech API use?

The API uses HTTP bearer authentication with an IBM Cloud IAM token. Through Jentic, the IAM credentials are stored in your Jentic One instance and the agent calls Watson via a scoped Jentic credential, never seeing the raw token.

### Can I synthesise text into an MP3 with this API?

Yes. POST the text and voice to `/v1/synthesize` and set the Accept header to audio/mp3. The endpoint also supports other formats including audio/wav and audio/ogg, and the choice of voice is constrained to the names returned by `/v1/voices.`

### How do I list the available voices?

GET `/v1/voices` returns the full set of named voices, including their language and gender. GET `/v1/voices/{voice}` returns the metadata for a specific voice, which is useful for surfacing voice attributes in a settings UI.

### How do I generate audio through Jentic?

Search Jentic for 'synthesise text to speech with IBM Watson', load the `/v1/synthesize` schema, and execute with the text and voice. Install the SDK with pip install jentic and use the async search, load, execute pattern from Python.

### What are the rate limits for the IBM Watson Text to Speech API?

Watson services apply IBM Cloud account-level rate limits rather than a published per-endpoint limit. Treat 429 responses as backpressure, retry with exponential backoff, and pre-render high-volume static prompts ahead of time.

### Can I limit what my agent is allowed to do with the IBM Watson Text to Speech API?

Yes. Because you self-host Jentic One, your own rules decide which Watson operations and credentials the agent may use, so you can allow only what it needs, such as synthesising audio through `/v1/synthesize` and listing voices through `/v1/voices.` An agent scoped to synthesis and voice reads cannot manage the custom pronunciation models under `/v1/customizations` unless you add those operations to its allowed set. The stored IAM token is injected at execution time and stays outside the agent's prompt and logs.