Name: Expressive Text-to-Speech API (Inworld Realtime TTS 1.5 Max)
Brand: magicapi
SKU: api-magicapi-realtime-text-to-speech-api-inworld-realtime-tts-1-5-max
Availability: InStock
Author: API Market

Shashank Agarwal

# 🔊 Expressive Text-to-Speech API (Inworld Realtime TTS 1.5 Max)

## Overview
The **Expressive Text-to-Speech API (Inworld Realtime TTS 1.5 Max)** turns text into speech with Inworld's Realtime TTS 1.5 Max model. Inworld describes it as its highest-quality realtime text-to-speech model, with under 200 ms latency, emotion control and support for 15 languages.

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. On api.market the API is asynchronous: you create a prediction, then poll it until the audio file is ready. It does not stream audio.

## Features
- **Emotion markups:** Inline tags such as `[happy]` or `[sad]` change how the following text is spoken.
- **Non-verbal vocalizations:** Inline tags such as `[laugh]` or `[sigh]`.
- **Pauses:** SSML break tags, for example `<break time="1s" />`.
- **Voices:** Use a preset voice name (examples given by Inworld: `Ashley`, `Dennis`, `Alex`) or a custom cloned voice ID. The default is `Ashley`.
- **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 Support Lines
Generate spoken replies and prompts, using `text_normalization` to control how numbers and dates are read out.

### Games and Characters
Give character lines emotion and non-verbal sounds with tags like `[happy]`, `[laugh]` or `[sigh]`.

### Narration and E-Learning
Produce voiceovers for lessons, explainers and videos, 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).

**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-1.5-max-output-api-market.mp3)

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.0044 per API unit.
- **1 API unit:** each started 100 characters of input `text`, rounded up per request. Tags and SSML in the text count toward the character total.
- **Worked example:** the 81-character example above is 1 unit ($0.0044). A 250-character request is 3 units, so it costs 3 x $0.0044 = $0.0132. The maximum of 2,000 characters is 20 units ($0.088).
- There is a single price for every voice, 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/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max
```

### 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. This is the request used for the example on this page:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "4a2e51066a48d694207736b7598590ac44a8c780d3ee50147951c5ddf3e52e1d",
    "input": {
      "text": "Welcome to api.market. Pick an API, grab your key, and start building in minutes."
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "4a2e51066a48d694207736b7598590ac44a8c780d3ee50147951c5ddf3e52e1d",
  "status": "starting",
  "created_at": "2026-10-12T10:44:46.526Z"
}
```

#### GET /predictions/{id}
Check the status of a prediction.
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max/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-1.5-max-output-api-market.mp3",
  "error": null,
  "created_at": "2026-10-12T10:44:46.526Z",
  "started_at": "2026-10-12T10:44:46.567Z",
  "completed_at": "2026-10-12T10:44:49.726Z"
}
```

`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 SSML break tags for pauses (e.g. `<break time="1s" />`), emotion markups (e.g. `[happy]`, `[sad]`) and non-verbal vocalizations (e.g. `[laugh]`, `[sigh]`). |
| `voice_id` | string | `Ashley` | A preset voice name (e.g. `Ashley`, `Dennis`, `Alex`) or a custom cloned voice ID | No | The voice to use. |
| `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/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max";
const version = "4a2e51066a48d694207736b7598590ac44a8c780d3ee50147951c5ddf3e52e1d";

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/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max"
VERSION = "4a2e51066a48d694207736b7598590ac44a8c780d3ee50147951c5ddf3e52e1d"

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/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "4a2e51066a48d694207736b7598590ac44a8c780d3ee50147951c5ddf3e52e1d",
    "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/realtime-text-to-speech-api-inworld-realtime-tts-1-5-max/predictions/PREDICTION_ID" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

### Tips
- Put an emotion tag right before the text it should affect, for example `[happy] We did it!`
- 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 control emotion?
Add emotion markups such as `[happy]` or `[sad]` in the text, and non-verbal tags such as `[laugh]` or `[sigh]` where you want them.

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

### Which languages are supported?
Inworld describes the model as supporting 15 languages. There is no language parameter; write the text in the language you want spoken.

### 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.


Text-to-speech with Inworld Realtime TTS 1.5 Max: up to 2,000 characters with emotion markups, non-verbal tags, SSML pauses and MP3, WAV, OGG or FLAC output.