Voices

Overview

Every Atlas voice is served two ways: a one-shot HTTP endpoint (POST /v1/audio/speech, OpenAI-compatible) and a WebSocket stream that returns audio sentence-by-sentence. Use the WebSocket service for interactive, real-time applications; use HTTP when you want a complete audio file per request.

HTTP endpoint reference

Full request/response reference for POST /v1/audio/speech.

Streaming reference

The WebSocket frame protocol for sentence-by-sentence audio.

Prerequisites

Account setup

Sign in to the Atlas playground.
Open API keys and create a key — the sk_… plaintext is shown only once.

Required environment variables

ATLAS_API_KEY=sk_...                                  # your secret API key
ATLAS_BASE_URL=https://api.tts.runatlas.com      # gateway base URL

Your sk_ key is a secret. Send it only from your server — never ship it in client-side code. Keys are stored hashed on our side and cannot be recovered, only rotated.

Configuration

Request parameters

string

required

The voice id, e.g. lylla. List available voices via /v1/models.

string

required

The text to speak.

string

default:"wav"

Output audio format: wav, mp3, pcm, opus, or flac. With pcm the HTTP response is streamed as it is synthesized.

string

Accepted for OpenAI SDK compatibility but ignored — the voice selects the model. Pass any placeholder (e.g. "atlas-tts").

Response headers

Header	Meaning
`x-upstream-ms`	Time spent in model inference for this request.
`x-gateway-ms`	Total gateway time. `x-gateway-ms − x-upstream-ms` = gateway overhead.

Usage

Generate a clip (HTTP)

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.tts.runatlas.com/v1",
    api_key=os.environ["ATLAS_API_KEY"],
)

with client.audio.speech.with_streaming_response.create(
    model="atlas-tts",
    voice="lylla",
    input="Hello from Lylla.",
    response_format="wav",
) as resp:
    resp.stream_to_file("out.wav")

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({
  baseURL: "https://api.tts.runatlas.com/v1",
  apiKey: process.env.ATLAS_API_KEY,
});

const res = await client.audio.speech.create({
  model: "atlas-tts",
  voice: "lylla",
  input: "Hello from Lylla.",
  response_format: "wav",
});
fs.writeFileSync("out.wav", Buffer.from(await res.arrayBuffer()));

Stream sentence-by-sentence (WebSocket)

Python

# pip install websockets
import asyncio, json, os, websockets

async def main():
    url = "wss://api.tts.runatlas.com/v1/audio/speech/stream"
    headers = [("Authorization", "Bearer " + os.environ["ATLAS_API_KEY"])]
    async with websockets.connect(url, additional_headers=headers) as ws:
        await ws.send(json.dumps({"type": "start", "voice": "lylla", "response_format": "wav"}))
        idx = 0
        async for msg in ws:
            if isinstance(msg, (bytes, bytearray)):       # per-sentence audio frame
                open(f"sentence_{idx}.wav", "wb").write(msg); idx += 1
                continue
            evt = json.loads(msg)
            if evt["type"] == "ready":
                await ws.send(json.dumps({"type": "text", "text": "Hello. This streams sentence by sentence."}))
                await ws.send(json.dumps({"type": "done"}))
            elif evt["type"] == "session.done":
                break

asyncio.run(main())

Notes

The standard catalogue is English; Hindi voices are available to enterprise accounts — contact us for access.
Hindi voices accept Devanagari or romanized Hindi (Hinglish) — "Kya haal hai?" and "क्या हाल है?" both work; romanized input is transliterated before synthesis.
The WebSocket service emits one binary audio frame per sentence — begin playback on the first frame for the lowest perceived latency.
Usage is metered per account in characters per day, with a per-minute request rate limit. 429 responses carry a quota_error body — see Errors.
The model request field is ignored; the voice is the sole selector.

Get started

API reference

Voices

Overview

HTTP endpoint reference

Streaming reference

Prerequisites

Account setup

Required environment variables

Configuration

Request parameters

Response headers

Usage

Generate a clip (HTTP)

Stream sentence-by-sentence (WebSocket)

Notes

​Overview

HTTP endpoint reference

Streaming reference

​Prerequisites

​Account setup

​Required environment variables

​Configuration

​Request parameters

​Response headers

​Usage

​Generate a clip (HTTP)

​Stream sentence-by-sentence (WebSocket)

​Notes

Overview

Prerequisites

Account setup

Required environment variables

Configuration

Request parameters

Response headers

Usage

Generate a clip (HTTP)

Stream sentence-by-sentence (WebSocket)

Notes