Text to speech API
built for people

curl -s https://api.inworld.ai/tts/v1/voice \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your ride is two minutes away. Look for a blue hatchback.",
    "voiceId": "Sarah",
    "modelId": "inworld-tts-2-flash",
    "audioConfig": {"audioEncoding": "MP3", "sampleRateHertz": 48000}
  }' | jq -r .audioContent | base64 --decode > ride.mp3

import base64, json, os, time, requests

start = time.perf_counter()
r = requests.post(
    "https://api.inworld.ai/tts/v1/voice:stream",
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "text": "Good morning. Light rain until ten, then sunshine for the rest of the day.",
        "voiceId": "Dennis",
        "modelId": "inworld-tts-2-flash",
        "audioConfig": {"audioEncoding": "MP3"},
    },
    stream=True,
)
r.raise_for_status()
with open("weather.mp3", "wb") as f:
    for line in r.iter_lines():  # NDJSON: one JSON object per line
        if not line:
            continue
        msg = json.loads(line)
        if "error" in msg:
            raise RuntimeError(msg["error"])
        if f.tell() == 0:
            print(f"first audio after {(time.perf_counter() - start) * 1000:.0f} ms")
        f.write(base64.b64decode(msg["result"]["audioContent"]))

import asyncio, base64, json, os, websockets

URL = "wss://api.inworld.ai/tts/v1/voice:streamBidirectional"
AUTH = {"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"}

async def main():
    async with websockets.connect(URL, additional_headers=AUTH) as ws:
        await ws.send(json.dumps({"contextId": "reply-1", "create": {
            "voiceId": "Olivia", "modelId": "inworld-tts-2-flash",
            "audioConfig": {"audioEncoding": "MP3"}}}))
        # text arrives in pieces, the way an LLM streams it
        for part in ["Sure, I can help with that. ", "Your order shipped this morning ", "and arrives on Thursday."]:
            await ws.send(json.dumps({"contextId": "reply-1", "send_text": {"text": part}}))
        await ws.send(json.dumps({"contextId": "reply-1", "flush_context": {}}))
        with open("reply.mp3", "wb") as f:
            async for raw in ws:
                result = json.loads(raw)["result"]
                if "audioChunk" in result:
                    f.write(base64.b64decode(result["audioChunk"]["audioContent"]))
                elif "flushCompleted" in result:
                    break
        await ws.send(json.dumps({"contextId": "reply-1", "close_context": {}}))

asyncio.run(main())

import base64, os, requests

r = requests.post(
    "https://api.inworld.ai/tts/v1/voice",
    headers={"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"},
    json={
        "text": "Turn left on Market Street, then walk two blocks to the station.",
        "voiceId": "Ashley",
        "modelId": "inworld-tts-2",
        "timestampType": "WORD",
        "audioConfig": {"audioEncoding": "MP3"},
    },
)
r.raise_for_status()
body = r.json()
open("directions.mp3", "wb").write(base64.b64decode(body["audioContent"]))
words = body["timestampInfo"]["wordAlignment"]
for word, t in zip(words["words"], words["wordStartTimeSeconds"]):
    if word.strip():
        print(f"{t:5.2f}s  {word.strip()}")

curl -s https://api.inworld.ai/tts/v1/voice \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "<lang lang=\"en-US\">You have to try the</lang> <lang lang=\"fr-FR\">croissant aux amandes.</lang> <lang lang=\"en-US\">[laugh] Trust me.</lang>",
    "voiceId": "Hana",
    "modelId": "inworld-tts-2",
    "instruction": "warm and playful, like a friend recommending a bakery",
    "audioConfig": {"audioEncoding": "MP3"}
  }' | jq -r .audioContent | base64 --decode > bakery.mp3

curl -s https://api.inworld.ai/voices/v1/voices:clone \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My voice",
    "languageCode": "en-US",
    "voiceSamples": [{"audioData": "'"$(base64 < sample.mp3 | tr -d '\n')"'"}]
  }' | jq -r .voice.voiceId