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. May contain inline audio tags for laughs, pauses, and emotional delivery.

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())

Voice cloning

You can make your own voice from a short reference clip and its exact transcript, then use it like any other voice. Voices are cloned from the clip and its words together — cloning from the clip alone is not supported. Create clones from the API with POST /v1/voices, or upload one in the playground.

Create a clone from the API

Send a WAV clip of 3–12 seconds of clean, single-speaker speech, base64-encoded, plus ref_text: exactly what is said in it, word for word (fillers included). Include a name and confirm you have permission to clone the voice. The voice is saved to your account immediately.

cURL

curl https://api.tts.runatlas.com/v1/voices \
  -H "Authorization: Bearer $ATLAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Narrator\", \"consent\": true, \"ref_text\": \"Hello, this is how I sound when I read aloud.\", \"audio_b64\": \"$(base64 < reference.wav | tr -d '\n')\"}"

The response’s id is the new voice id:

{ "id": "tmp-a1b2c3-x9y8z7", "object": "voice", "name": "Narrator", "created": 1791454123, "owned_by": "user", "reference_seconds": 5.2 }

To remove a clone, call DELETE /v1/voices/{id}.

Create a clone in the playground

In the Atlas playground, pick an English voice and click Upload your voice.
Upload your clip, type exactly what is said in it, and confirm you have permission to clone the voice.
Generate some speech to hear the result. When you are happy with it, give it a name and click Add to my library.

An uploaded voice that you don’t add to your library is temporary and expires after about an hour. Each account can keep up to 10 saved voices, whether you created them from the API or the playground. To add another, delete one first.

Use a clone

Saved clones appear in /v1/models with owned_by: "user". Pass the clone’s id as voice, the same as for a global voice:

from openai import OpenAI
import os

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

# Find your own clones
clones = [m.id for m in client.models.list() if m.owned_by == "user"]

with client.audio.speech.with_streaming_response.create(
    model="atlas-tts",
    voice=clones[0],
    input="This is my own voice.",
    response_format="wav",
) as resp:
    resp.stream_to_file("clone.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,
});

// Find your own clones
const clones = (await client.models.list()).data.filter((m) => m.owned_by === "user");

const res = await client.audio.speech.create({
  model: "atlas-tts",
  voice: clones[0].id,
  input: "This is my own voice.",
  response_format: "wav",
});
fs.writeFileSync("clone.wav", Buffer.from(await res.arrayBuffer()));

Clones work over both the HTTP endpoint and the WebSocket stream, and they accept the same audio tags. They are private: only API keys belonging to the account that saved a clone can use it. Any other key gets an unknown-voice error.

Cloning is English-only. Multilingual (indic-*) voices use fixed trained speakers and do not support cloning.

Customizing speech

Delivery is controlled with inline tokens in the input text — no SSML required. Event tags insert a single transient sound:

<|laugh|> My uncle fed the robot vacuum milk.
She read it twice, <|sigh|> and still missed the clause.

Style wraps color a span of speech — a sentence or part of one — with an emotion or accent:

<|style_open|>excited<|style_body|> I finally got the offer! <|style_close|>

The ember voice uses free-form [bracket] cues instead ([chuckling], [whisper in small voice]). See the audio tags guide for both vocabularies, placement rules, and a worked example.

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.
Clones need a transcript. A clone made before transcripts were required has none, and synthesis with it is rejected with 400 naming the voice — create it again with ref_text (API) or the transcript box (playground).

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)

Voice cloning

Create a clone from the API

Create a clone in the playground

Use a clone

Customizing speech

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)

​Voice cloning

​Create a clone from the API

​Create a clone in the playground

​Use a clone

​Customizing speech

​Notes

Overview

Prerequisites

Account setup

Required environment variables

Configuration

Request parameters

Response headers

Usage

Generate a clip (HTTP)

Stream sentence-by-sentence (WebSocket)

Voice cloning

Create a clone from the API

Create a clone in the playground

Use a clone

Customizing speech

Notes