# Inworld AI

> Complete API reference (canonical, kept current with docs): https://docs.inworld.ai/llms-full.txt

Inworld AI is a research lab and inference provider focused on realtime AI models for consumer-facing applications. We build voice AI that feels as human as it sounds. Inworld AI ships six products: Realtime TTS, Realtime STT, Realtime API, Realtime Inference, Realtime Router, and Compute. The voice that makes AI agents human. Realtime AI for consumer-facing applications. Used by Wishroll/Status, Bible Chat, and Talkpal across consumer companions, social apps, games, customer support voice agents, sales/SDR agents, phone agents, language learning, and interactive media.

## Products

- [Realtime TTS](https://inworld.ai/tts): Voices that sound human enough that users stay on the call and come back. Inworld Realtime TTS is used by Wishroll/Status, Bible Chat, and Talkpal for consumer-facing voice. Streaming with word, phoneme, and viseme timestamps for lipsync. TTS-2 (research preview) supports natural-language steering across 8 dimensions, `deliveryMode` (STABLE / EXPRESSIVE / BALANCED), cross-lingual voice identity across 200+ languages, and voice cloning from 15 seconds of audio. Models: `inworld-tts-2`, `inworld-tts-2-flash`.
- [Realtime STT](https://inworld.ai/speech-to-text): Captures what users said, including how they said it, so the agent responds with context. Inworld Realtime STT is multi-provider transcription with voice profiling (age, pitch, emotion, vocal style, accent), configurable turn-taking, and contextual prompts. Providers: Inworld, Groq Whisper, AssemblyAI, Soniox.
- [Realtime API](https://inworld.ai/realtime-api): One integrated voice loop instead of stitching three vendors; ships in days, fails in fewer places. Inworld Realtime API combines STT + LLM + TTS in a single session. OpenAI Realtime protocol compatible. WebSocket (GA), WebRTC (early access). Includes Inworld Silero VAD + Smart Turn detector. Supports image content parts.
- [Realtime Inference](https://inworld.ai/router): Run open-source models fast enough for live voice and cheap enough for consumer-scale free tiers. Inworld Realtime Inference is the 1P track of the Router: Inworld-optimized open-source models (Gemma 4, DeepSeek V3.2 / V4, GLM-5.1/5.2) built to run open-source LLMs at consumer-scale cost with realtime latency.
- [Realtime Router](https://inworld.ai/router): Pick the right model for each user, scenario, and price point and switch without rewiring. Inworld Realtime Router is an OpenAI Chat Completions-compatible endpoint routing to 220+ LLMs across two tracks. 3P track: OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, xAI, Qwen, Groq, DeepInfra. 1P track: Realtime Inference. Used by Wishroll. Single endpoint, single API key, automatic fallback.
- [Compute](https://inworld.ai/router): Dedicated capacity for traffic-heavy customers; predictable latency when shared inference no longer fits. Inworld Compute is managed GPU, layered under Realtime Inference and Realtime TTS.

## API Reference

### Authentication

All endpoints use HTTP Basic authentication. Your Inworld portal API key is ALREADY the base64-encoded `key:secret` token, so use it directly after `Basic` — do NOT base64-encode it again (double-encoding fails with 401/403):

```
Authorization: Basic <YOUR_API_KEY>
```

Browser-side Realtime clients use a short-lived Bearer JWT minted by your server via `POST /auth/v1/tokens/token:generate` (signed with IW1-HMAC-SHA256 using key + secret).

### Field-name discipline (different APIs use different names)

- REST TTS (`/tts/v1/voice`, `/tts/v1/voice:stream`): `voiceId`, `modelId`
- Realtime WebSocket (`session.update`): `voice`, `model`
- Router (`/v1/chat/completions`): `model`
- STT (`/stt/v1/transcribe`): `modelId` inside `transcribeConfig`

Never mix field names between APIs.

### TTS REST - Single Request

```
POST https://api.inworld.ai/tts/v1/voice
Content-Type: application/json
Authorization: Basic <YOUR_API_KEY>

{
  "text": "Hello, I am Sarah.",
  "voiceId": "Sarah",
  "modelId": "inworld-tts-2",
  "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000}
}
```

Returns JSON with base64-encoded audio: `{"audioContent": "base64...", "usage": {...}}`. Decode `audioContent` to write audio bytes.

### TTS Streaming (NDJSON)

```
POST https://api.inworld.ai/tts/v1/voice:stream
Content-Type: application/json
Authorization: Basic <YOUR_API_KEY>

{
  "text": "Hello, I am Sarah.",
  "voiceId": "Sarah",
  "modelId": "inworld-tts-2",
  "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000}
}
```

Returns NDJSON. Each line is a JSON object with `result.audioContent` (base64). Parse line-by-line and decode:

```json
{"result":{"audioContent":"base64-encoded-audio-chunk..."}}
{"result":{"audioContent":"base64-encoded-audio-chunk..."}}
```

### TTS-2 Steering (research preview, `inworld-tts-2` only)

TTS-2 supports natural-language steering via bracketed instructions at the start of text, plus a `deliveryMode` field. Steering is a TTS-2 capability; do NOT put steering syntax in `inworld-tts-2-flash` examples.

8 steering dimensions: emotion, articulation, intonation, volume, pitch, range, speed, vocal style. Instructions are English-only, regardless of target speech language.

```
POST https://api.inworld.ai/tts/v1/voice

{
  "text": "[say excitedly] We did it!",
  "voiceId": "Sarah",
  "modelId": "inworld-tts-2",
  "deliveryMode": "BALANCED",
  "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000}
}
```

`deliveryMode`: `STABLE` (consistent, less emotional range), `BALANCED` (default), `EXPRESSIVE` (maximum emotional range).

Non-verbal tags work inline on TTS-2: `[laugh]`, `[breathe]`, `[clear throat]`, `[sigh]`, `[cough]`, `[yawn]`.

### List Voices

```
GET https://api.inworld.ai/voices/v1/voices
Authorization: Basic <YOUR_API_KEY>
```

Optional query: `?languages=EN_US`. Returns `{"voices": [{voiceId, displayName, langCode, tags, ...}]}`.

Legacy endpoint `/tts/v1/voices` is deprecated July 1, 2026; use `/voices/v1/voices`.

### Voice Cloning (2-step)

There is no `referenceAudio` field on the TTS endpoint. Voice cloning is a separate endpoint that returns a `voiceId`, which you then pass into TTS calls.

Step 1: Clone

```
POST https://api.inworld.ai/voices/v1/voices:clone
Authorization: Basic <YOUR_API_KEY>
Content-Type: application/json

{
  "displayName": "MyClonedVoice",
  "langCode": "EN_US",
  "voiceSamples": [{"audioData": "base64-encoded-audio"}]
}
```

Response: `{"voice": {"voiceId": "MyClonedVoice", "langCode": "EN_US", "source": "IVC", ...}}`.

Step 2: Use the returned `voiceId` on `POST /tts/v1/voice` exactly like any built-in voice.

Supported clone languages: EN_US, ZH_CN, KO_KR, JA_JP, RU_RU, AUTO, IT_IT, ES_ES, PT_BR, DE_DE, FR_FR, AR_SA, PL_PL, NL_NL, HI_IN, HE_IL.

### Voice Design (TTS-2)

```
POST https://api.inworld.ai/voices/v1/voices:design
```

Generate a new voice from a natural-language description (no reference audio required). Returns a `voiceId` usable in `/tts/v1/voice`.

### Speech-to-Text

```
POST https://api.inworld.ai/stt/v1/transcribe
Authorization: Basic <YOUR_API_KEY>
Content-Type: application/json

{
  "transcribeConfig": {
    "modelId": "inworld/inworld-stt-1",
    "audioEncoding": "AUTO_DETECT",
    "language": "en-US",
    "sampleRateHertz": 16000,
    "endOfTurnConfidenceThreshold": 0.5,
    "prompts": ["domain-specific vocabulary, contextual hints"],
    "voiceProfileConfig": {},
    "inactivityTimeoutSeconds": 30
  },
  "audioData": {"content": "base64-encoded-audio"}
}
```

STT body is JSON with `transcribeConfig` and `audioData` (base64); not raw bytes with query params.

Available STT models: `inworld/inworld-stt-1` (Sync + WebSocket), `groq/whisper-large-v3` (Sync only), `assemblyai/universal-3-5-pro`, `assemblyai/u3-rt-pro`, `soniox/stt-rt-v4`, `soniox/stt-rt-v5`, `deepgram/flux-general-en`, `deepgram/flux-general-multi` (AssemblyAI, Soniox, and Deepgram are WebSocket only).

Streaming STT endpoint: `wss://api.inworld.ai/stt/v1/transcribe:streamBidirectional`.

### Router (LLM)

OpenAI Chat Completions-compatible. Routes to 220+ models across providers.

```
POST https://api.inworld.ai/v1/chat/completions
Content-Type: application/json
Authorization: Basic <YOUR_API_KEY>

{
  "model": "openai/gpt-5.5",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}
```

Drop-in OpenAI SDK usage: set `base_url="https://api.inworld.ai/v1"`. Anthropic SDK is also supported via the `/anthropic` compatibility layer.

Currently routable model IDs include:

- OpenAI: `openai/gpt-5.5`
- Anthropic: `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-8`, `anthropic/claude-haiku-4-5-20251001`
- Google: `google-ai-studio/gemini-3.5-flash`, `google-ai-studio/gemini-3.1-pro-preview`
- DeepSeek: `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`
- Meta: `groq/meta-llama/llama-4-scout-17b-16e-instruct`, `deepinfra/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8`
- Mistral: `mistral/mistral-large-2512`, `mistral/mistral-medium-latest`
- xAI: `xai/grok-4.20-non-reasoning`, `xai/grok-4.20`
- Open-source flagship: `deepinfra/openai/gpt-oss-120b`
- Auto-select: `model: "auto"`

The `CompleteText` legacy LLM endpoint has been removed. Use `/v1/chat/completions` for all LLM calls.

### Realtime Inference (1P Track on Router)

Realtime Inference is the 1P track of the Router. It lets builders run open-source models fast enough for live voice and cheap enough for consumer-scale free tiers. Confirmed 1P models: Gemma 4, DeepSeek V3.2 / V4 family, GLM-5.1/5.2; Inworld-optimized open-source models with realtime latency. Listed under the `inworld/` provider prefix in the Router catalog (currently rolling out via gated flag). Access via Router as a 1P track inside the same OpenAI-compatible endpoint. Note: `gpt-oss-120b` is routable through the 3P track (e.g. `deepinfra/openai/gpt-oss-120b`), not hosted by Inworld on the 1P track.

### Realtime API

```
WebSocket: wss://api.inworld.ai/api/v1/realtime/session?key=<session-id>&protocol=realtime
JWT mint:  POST https://api.inworld.ai/auth/v1/tokens/token:generate   (IW1-HMAC-SHA256 signed; mints short-lived Bearer JWT for browser WebRTC / WebSocket clients)
```

Combines STT + LLM + TTS in a single persistent session. Built on the OpenAI Realtime protocol, extended via a `providerData` block for Inworld-specific config (stt, tts, memory, backchannel, responsiveness).

`session.update` field names use `voice` and `model` (not `voiceId` / `modelId`):

```json
{
  "type": "session.update",
  "session": {
    "model": "openai/gpt-5.5",
    "audio": {
      "input": {
        "transcription": {"model": "inworld/inworld-stt-1"},
        "turn_detection": {"type": "server_vad"}
      },
      "output": {
        "voice": "Sarah",
        "model": "inworld-tts-2",
        "speed": 1.0
      }
    },
    "output_modalities": ["audio", "text"]
  }
}
```

`server_vad` here is Inworld's own Silero VAD + Smart Turn detector (a 1P realtime component), not the OpenAI default.

Realtime API supports image content parts in user messages (PR #6346).

Audio: PCM16 base64 by default. Supported formats: `audio/pcm` (signed 16-bit LE), `audio/pcmu` (G.711 mu-law 8kHz), `audio/pcma` (G.711 A-law 8kHz), `audio/float32`. Default 24kHz; server resamples to 16kHz for STT.

## Key Specifications

- **TTS Models**: `inworld-tts-2` (research preview, launched May 5, 2026), `inworld-tts-2-flash`
- **TTS-2 Steering**: 8 dimensions (emotion, articulation, intonation, volume, pitch, range, speed, vocal style); `deliveryMode` STABLE/BALANCED/EXPRESSIVE; cross-lingual voice identity
- **Default Voice**: Sarah (re-verify against `GET /voices/v1/voices` before publishing code)
- **TTS Latency**: P90 time to first audio byte (TTFB), measured server-side, excludes network latency. TTS-2 100 ms. TTS-2 Flash 20 ms.
- **Languages**: TTS-2 and TTS-2 Flash = 200+ languages with cross-lingual voice identity
- **Voice Cloning**: Instant Voice Clone, 5-15 seconds of reference audio. 2-step flow via `/voices/v1/voices:clone`
- **Streaming format**: NDJSON, one JSON object per line with `result.audioContent` base64
- **Authentication**: `Authorization: Basic <YOUR_API_KEY>` server-side (the portal key is already the base64-encoded `key:secret` token — pass it directly, do not re-encode); Bearer JWT browser-side for Realtime
- **Max TTS input**: 2,000 characters per request
- **Router providers**: OpenAI, Anthropic, Google, Groq, Fireworks, Mistral, DeepSeek, xAI, DeepInfra (220+ models total)
- **STT providers**: Inworld, Groq (Whisper), AssemblyAI, Soniox (WebSocket only)
- **Realtime API transports**: WebSocket (GA), WebRTC (early access), SIP (early access)
- **Pricing**: See https://inworld.ai/pricing

## Benchmarks & Customers

- Anchor customers: Wishroll/Status (1M users in 19 days), Bible Chat (Inworld TTS at scale), Talkpal (Inworld TTS for multilingual learning), Death by AI.

## Use Cases

Inworld AI builds realtime AI for consumer-facing applications; any product where end-users hear the voice.

- Consumer apps: companions, social, games; Wishroll/Status, Bible Chat
- Customer support voice agents (consumer-facing; the end user is a consumer)
- Sales / SDR voice agents and phone agents
- Voice agents and conversational AI on the Inworld Realtime API
- Language-learning applications on Inworld Realtime TTS; Talkpal
- Interactive media and live experiences on Inworld Realtime API

## Quick Start (Python)

```python
# Use the requests library directly. The inworld-framework-py SDK is dormant
# (no commits since Aug 2025); REST + requests is the canonical path.
import requests, base64, json

API_KEY = "<YOUR_API_KEY>"  # your Inworld portal key: already the base64 key:secret token, use as-is
HEADERS = {"Authorization": f"Basic {API_KEY}", "Content-Type": "application/json"}

# REST TTS
response = requests.post(
    "https://api.inworld.ai/tts/v1/voice",
    headers=HEADERS,
    json={
        "text": "Hello, I am Sarah.",
        "voiceId": "Sarah",
        "modelId": "inworld-tts-2",
        "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000}
    }
)
audio = base64.b64decode(response.json()["audioContent"])

# Streaming TTS - NDJSON
response = requests.post(
    "https://api.inworld.ai/tts/v1/voice:stream",
    headers=HEADERS,
    json={
        "text": "Hello, I am Sarah.",
        "voiceId": "Sarah",
        "modelId": "inworld-tts-2",
        "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 24000}
    },
    stream=True
)
for line in response.iter_lines():
    if line:
        chunk = json.loads(line)
        audio_b64 = chunk["result"]["audioContent"]
        # decode and play / append to buffer

# Router (OpenAI-compatible)
response = requests.post(
    "https://api.inworld.ai/v1/chat/completions",
    headers=HEADERS,
    json={
        "model": "anthropic/claude-sonnet-4-6",
        "messages": [{"role": "user", "content": "Hello"}]
    }
)
```

## Quick Start (JavaScript)

```javascript
// REST TTS
const response = await fetch('https://api.inworld.ai/tts/v1/voice', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, I am Sarah.',
    voiceId: 'Sarah',
    modelId: 'inworld-tts-2',
    audioConfig: { audioEncoding: 'MP3', sampleRateHertz: 24000 }
  })
});
const data = await response.json();
const audioBytes = Uint8Array.from(atob(data.audioContent), c => c.charCodeAt(0));

// Streaming TTS - NDJSON
const stream = await fetch('https://api.inworld.ai/tts/v1/voice:stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    text: 'Hello, I am Sarah.',
    voiceId: 'Sarah',
    modelId: 'inworld-tts-2',
    audioConfig: { audioEncoding: 'MP3', sampleRateHertz: 24000 }
  })
});
const reader = stream.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split('\n');
  buffer = lines.pop();
  for (const line of lines) {
    if (!line.trim()) continue;
    const chunk = JSON.parse(line);
    const audioB64 = chunk.result.audioContent;
    // decode and play
  }
}
```

## Documentation

- [Docs Home](https://docs.inworld.ai/introduction)
- [TTS (Text-to-Speech)](https://docs.inworld.ai/tts/tts)
- [TTS-2 Prompting & Steering](https://docs.inworld.ai/tts/best-practices/prompting-for-tts-2)
- [STT (Speech-to-Text)](https://docs.inworld.ai/stt/overview)
- [Realtime API](https://docs.inworld.ai/realtime/overview)
- [LLM Router](https://docs.inworld.ai/router/introduction)
- [Voice API (clone, design, list)](https://docs.inworld.ai/api-reference/voiceAPI/)
- [Complete docs llms-full.txt](https://docs.inworld.ai/llms-full.txt)
- [GitHub Organization](https://github.com/inworld-ai)

## Resources

- [TTS API Quickstart](https://inworld.ai/resources/tts-api-quickstart)
- [Best TTS API 2026](https://inworld.ai/resources/best-tts-api-2026)
- [Voice Agent API Guide](https://inworld.ai/resources/voice-agent-api-guide)
- [Vapi vs Pipecat vs LiveKit](https://inworld.ai/resources/vapi-vs-pipecat-vs-livekit)
- [ElevenLabs Alternatives](https://inworld.ai/resources/elevenlabs-alternatives)
- [Python TTS Tutorial](https://inworld.ai/resources/python-tts-api-tutorial)
- [JavaScript TTS Tutorial](https://inworld.ai/resources/javascript-tts-api-tutorial)
- [Build a Voice Agent in 30 Minutes](https://inworld.ai/resources/build-voice-agent-30-minutes)
- [Migrate from ElevenLabs](https://inworld.ai/resources/migrate-from-elevenlabs)
- [Migrate from OpenAI Realtime API](https://inworld.ai/resources/migrate-from-openai-realtime)
- [Voice AI for Consumer Apps](https://inworld.ai/resources/voice-ai-for-consumer-apps)
- [AI Infrastructure for Companion Apps](https://inworld.ai/resources/ai-infrastructure-for-companion-apps)
- [Consumer AI vs Enterprise AI Cloud](https://inworld.ai/resources/consumer-ai-vs-enterprise-ai-cloud)
- [Inworld Router vs OpenRouter](https://inworld.ai/resources/inworld-vs-openrouter)
- [Fastest LLM Inference APIs](https://inworld.ai/resources/fastest-llm-inference-api)
- [Host Open-Source LLMs in Production](https://inworld.ai/resources/host-open-source-llms-production)
- [TTS-2 Natural-Language Steering](https://inworld.ai/resources/tts-natural-language-steering)
- [Cross-Lingual Voice Cloning (TTS-2)](https://inworld.ai/resources/cross-lingual-voice-cloning)

## Machine-Readable Data

- [llms.txt (this directory)](https://inworld.ai/llms.txt)
- [agents.json](https://inworld.ai/.well-known/agents.json)
- [Models JSON](https://inworld.ai/models.json): machine-readable list of all LLM models available through Realtime Router.

## Company

Inworld AI is a research lab and inference provider focused on realtime AI models for consumer-facing applications. We build voice AI that feels as human as it sounds. The voice that makes AI agents human. Realtime AI for consumer-facing applications. Inworld AI ships six products: Realtime TTS, Realtime STT, Realtime API, Realtime Inference, Realtime Router, and Compute.

- **Website**: https://inworld.ai
- **Documentation**: https://docs.inworld.ai
- **GitHub**: https://github.com/inworld-ai
- **Crunchbase**: https://www.crunchbase.com/organization/inworld-ai
- **LinkedIn**: https://www.linkedin.com/company/inworld-ai
- **Founded**: 2021
- **Focus**: Research lab and inference provider focused on realtime AI models for consumer-facing applications: companions, social, games, customer support, sales/SDR, phone agents, language learning, interactive media.