Name: Expressive Text-to-Speech API (Inworld Realtime TTS 2)
Brand: magicapi
SKU: api-magicapi-expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔊 Expressive Multilingual Text-to-Speech API (Inworld Realtime TTS 2)

## Overview
The **Expressive Multilingual Text-to-Speech API (Inworld Realtime TTS 2)** turns text into speech with Inworld's Realtime TTS 2 model. Inworld describes it as its most expressive text-to-speech model, with natural-language steering: you write short instructions in square brackets (for example `[say excitedly]` or `[whisper in a hushed style]`) in front of the text they apply to, and the model changes how it speaks.

You send up to 2,000 characters of text, pick a voice, and get back a URL to the finished audio file in MP3, WAV, OGG Opus or FLAC. Requests run asynchronously: you create a prediction, then poll it until the audio is ready.

## Features
- **Natural-language steering:** Bracketed instructions placed before the text they apply to, such as `[say excitedly]`, `[whisper in a hushed style]` or `[say sadly with deliberate pauses in a low voice]`.
- **Non-verbal tags:** Inline tags such as `[laugh]`, `[sigh]`, `[breathe]`, `[clear throat]`, `[cough]` and `[yawn]`.
- **Pauses and emphasis:** SSML break tags for pauses (for example `<break time="1s" />`) and capitalized words for emphasis (for example `I told you NOT to do that`).
- **Voices:** Use a preset voice name (examples given by Inworld: `Ashley`, `Dennis`, `Alex`, `Darlene`) or a custom cloned voice ID. The default is `Ashley`.
- **15 production languages plus auto-detect:** English (en), Chinese (zh), Japanese (ja), Korean (ko), Russian (ru), Italian (it), Spanish (es), Portuguese (pt), French (fr), German (de), Polish (pl), Dutch (nl), Hindi (hi), Hebrew (he) and Arabic (ar), or `auto` to let the model detect the language.
- **Output formats:** `mp3` (default), `wav`, `ogg_opus` or `flac`.
- **Sample rates:** 8000, 16000, 22050, 24000, 32000, 44100 or 48000 Hz (default 48000).
- **Delivery controls:** `temperature` for more or less expressive variation, `speaking_rate` for speed, and `text_normalization` to control how numbers, dates and abbreviations are read.

## Use Cases
### Voice Agents and Phone Systems
Read confirmation numbers, order details and prompts with a clear delivery, using `text_normalization` to control how numbers and dates are spoken.

### Games, Animation and Characters
Give characters emotion and non-verbal sounds with bracketed instructions and tags like `[laugh]` or `[sigh]`.

### Narration and E-Learning
Produce lessons and explainers in any of the 15 supported languages, adjusting pace with `speaking_rate` and adding pauses with SSML break tags.

### Accessibility
Turn written content into spoken audio for users who prefer or need to listen.

## Visual Examples
This is the real request we sent through api.market and the audio it produced. Only `text` was set, so the defaults applied (voice `Ashley`, `mp3` at 48000 Hz, language `auto`).

**Text used:**
> Welcome to api.market. Pick an API, grab your key, and start building in minutes.

**Output:** [Listen to the example](https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-2-output-api-market.mp3)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.0032 per API unit.
- **1 API unit:** each started 100 characters of input `text`. Bracketed instructions, tags and SSML in the text count toward the character total.
- **Worked example:** a 250-character request is 3 units, so it costs 3 x $0.0032 = $0.0096. The 81-character example above is 1 unit ($0.0032). The maximum of 2,000 characters is 20 units ($0.064).
- There is a single price for every voice, language, format and sample rate.
- **Failed or cancelled predictions** are not billed.
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation
### Base URL
```
https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2
```

### Authentication
Include your api.market API key in the `x-api-market-key` header of every request:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.
1. Send `POST /predictions` with the model `version` and your `input`. A successful call returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`. 201 means the prediction was accepted; it is not an error.
2. Poll `GET /predictions/{id}` every second or two.
3. Stop when `status` is `succeeded` (the `output` field holds the audio URL), `failed` (see the `error` field) or `canceled`.

### Endpoints

#### POST /predictions
Create a prediction.
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ff2e08e7e058fa4d45e2179da92a390e2d7803f879542136c3deb7d6c809181b",
    "input": {
      "text": "Welcome to api.market. Pick an API, grab your key, and start building in minutes."
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "ff2e08e7e058fa4d45e2179da92a390e2d7803f879542136c3deb7d6c809181b",
  "status": "starting",
  "created_at": "2026-10-11T19:10:31.361Z"
}
```

#### GET /predictions/{id}
Check the status of a prediction.
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/realtime-tts-2-output-api-market.mp3",
  "error": null,
  "created_at": "2026-10-11T19:10:31.361Z",
  "started_at": "2026-10-11T19:10:31.402Z",
  "completed_at": "2026-10-11T19:10:34.118Z"
}
```

`output` is a single URL to the generated audio file.

### Input Parameters
| Parameter | Type | Default | Allowed values | Required | Description |
|---|---|---|---|---|---|
| `text` | string | none | Up to 2,000 characters | Yes | The text to convert to speech. Supports bracketed steering instructions placed before the text they apply to (e.g. `[say excitedly]`), inline non-verbal tags (e.g. `[laugh]`, `[sigh]`, `[breathe]`, `[clear throat]`, `[cough]`, `[yawn]`), SSML break tags (e.g. `<break time="1s" />`) and capitalized words for emphasis. |
| `voice_id` | string | `Ashley` | A preset voice name (e.g. `Ashley`, `Dennis`, `Alex`, `Darlene`) or a custom cloned voice ID | No | The voice to use. |
| `language` | string | `auto` | `auto`, `en`, `zh`, `ja`, `ko`, `ru`, `it`, `es`, `pt`, `fr`, `de`, `pl`, `nl`, `hi`, `he`, `ar` | No | Language of the input text. `auto` lets the model detect it. |
| `temperature` | number | `0` | 0 to 2 | No | Controls randomness. Higher values are more expressive, lower values more deterministic. `0` uses the model default (1.1). |
| `audio_format` | string | `mp3` | `mp3`, `wav`, `ogg_opus`, `flac` | No | Output audio format. |
| `sample_rate` | integer | `48000` | `8000`, `16000`, `22050`, `24000`, `32000`, `44100`, `48000` | No | Audio sample rate in Hz. |
| `speaking_rate` | number | `0` | 0 to 1.5 | No | Speaking speed multiplier. `0` means normal speed (1.0). |
| `text_normalization` | string | `auto` | `auto`, `on`, `off` | No | Whether numbers, dates and abbreviations are expanded before synthesis. `auto` lets the model decide, `on` always normalizes, `off` reads the text as-is. |

### Status Codes
- **201 Created:** Prediction created (POST). This is the normal success response.
- **200 OK:** Prediction details returned (GET).
- **400 Bad Request:** Invalid input, for example a missing `text` or a value outside the allowed range.
- **401 Unauthorized:** Missing or invalid API key.
- **404 Not Found:** No prediction with that ID.
- **429 Too Many Requests:** Too many requests in a short time. Wait and retry.
- **500 Internal Server Error:** Server-side error. Retry after a short wait.

### Error Handling
- A 201 response only means the prediction was accepted. Always poll until `status` is `succeeded`, `failed` or `canceled`.
- When `status` is `failed`, read the `error` field, fix the input and send a new request. Failed predictions are not billed.
- For 429 and 5xx responses, retry with exponential backoff.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Implementation Guide
### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2";
const version = "ff2e08e7e058fa4d45e2179da92a390e2d7803f879542136c3deb7d6c809181b";

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function generateSpeech(input) {
  const createResponse = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version, input })
  });
  if (createResponse.status !== 201 && createResponse.status !== 200) {
    throw new Error(`API error: ${createResponse.status} ${await createResponse.text()}`);
  }
  const { id } = await createResponse.json();

  const deadline = Date.now() + 10 * 60 * 1000;
  while (Date.now() < deadline) {
    const pollResponse = await fetch(`${baseUrl}/predictions/${id}`, {
      headers: { "x-api-market-key": apiKey }
    });
    if (!pollResponse.ok) {
      throw new Error(`API error: ${pollResponse.status} ${await pollResponse.text()}`);
    }
    const prediction = await pollResponse.json();
    if (prediction.status === "succeeded") return prediction.output;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "unknown error"}`);
    }
    await delay(1000);
  }
  throw new Error("Prediction timed out after 10 minutes");
}

generateSpeech({
  text: "Welcome to api.market. Pick an API, grab your key, and start building in minutes."
}).then((audioUrl) => console.log("Audio:", audioUrl));
```

### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2"
VERSION = "ff2e08e7e058fa4d45e2179da92a390e2d7803f879542136c3deb7d6c809181b"

def generate_speech(input_data, timeout_seconds=600):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": VERSION, "input": input_data},
    )
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")
    prediction_id = response.json()["id"]

    deadline = time.time() + timeout_seconds
    while time.time() < deadline:
        poll = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers={"x-api-market-key": API_KEY},
        )
        poll.raise_for_status()
        prediction = poll.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error')}")
        time.sleep(1)
    raise TimeoutError("Prediction timed out")

audio_url = generate_speech({
    "text": "Welcome to api.market. Pick an API, grab your key, and start building in minutes."
})
print("Audio:", audio_url)
```

### cURL
```bash
# Step 1: create the prediction (returns 201 with an id)
curl -X POST "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "ff2e08e7e058fa4d45e2179da92a390e2d7803f879542136c3deb7d6c809181b",
    "input": {
      "text": "Welcome to api.market. Pick an API, grab your key, and start building in minutes."
    }
  }'

# Step 2: poll with the id from step 1 until status is succeeded, failed or canceled
curl -X GET "https://prod.api.market/api/v1/magicapi/expressive-multilingual-text-to-speech-api-inworld-realtime-tts-2/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Tips
- Put a bracketed instruction right before the sentence it should affect, for example `[say sadly with deliberate pauses in a low voice] I miss you.`
- Leave `temperature` and `speaking_rate` at `0` to use the model defaults (1.1 and 1.0), then adjust from there.
- Set `text_normalization` to `off` if you want numbers and abbreviations read exactly as written.
- Cost depends only on text length, so trimming unneeded text lowers the price.

## FAQ
### How long can the text be?
Up to 2,000 characters per request.

### How do I change the speaking style?
Write an instruction in square brackets before the text it applies to, such as `[say excitedly]` or `[whisper in a hushed style]`. You can also add tags like `[laugh]` or `[sigh]` inline.

### Which languages can I use?
The `language` parameter accepts `en`, `zh`, `ja`, `ko`, `ru`, `it`, `es`, `pt`, `fr`, `de`, `pl`, `nl`, `hi`, `he` and `ar`, or `auto` (the default) to detect the language from the text.

### Which voices are available?
Pass a preset voice name in `voice_id`. Inworld's examples are `Ashley` (the default), `Dennis`, `Alex` and `Darlene`. The field also accepts a custom cloned voice ID.

### Does this stream audio?
No. This API returns a finished audio file URL once the prediction succeeds.

### What happens if a prediction fails?
It is not billed. Read the `error` field, fix the input and try again.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Inworld Realtime TTS 2 API: expressive speech from text with bracketed style steering, non-verbal tags, 15 languages and MP3, WAV, OGG Opus or FLAC output.