API Documentation

Quickstart — 5 minutes

No SDK required. Just Python and a WebSocket library.

pip install websockets

import asyncio, websockets, json

async def demo():
    uri = "wss://voice.knewcleus.app/v1/stream/demo"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "text":  "Hello from SonicWeaver.",
            "voice": "af_bella"
        }))
        async for msg in ws:
            if isinstance(msg, bytes):
                print(f"Audio chunk: {len(msg)} bytes")
            elif json.loads(msg).get("type") == "done":
                print("Done.")
                break

asyncio.run(demo())

import asyncio, websockets, json

API_KEY = "sw_live_your_key_here"

async def synthesize(text: str, voice: str = "af_bella") -> bytes:
    uri = f"wss://voice.knewcleus.app/v1/stream?api_key={API_KEY}"
    pcm = []
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({"text": text, "voice": voice}))
        async for msg in ws:
            if isinstance(msg, bytes):
                pcm.append(msg)
            else:
                data = json.loads(msg)
                if data.get("type") == "done":
                    print(f"Credits remaining: {data.get('credits_remaining')}")
                    break
                if data.get("type") == "error":
                    raise Exception(data.get("message"))
    return b"".join(pcm)  # Raw PCM — see Audio Format section

asyncio.run(synthesize("Your appointment is tomorrow at 2 PM."))

Authentication

SonicWeaver supports two authentication methods:

Get your API key at /developers. Keys do not expire unless revoked.

WebSocket endpoint

Protocol — sending and receiving

You send (JSON):

{
  "text":         "Your text here",   // required, max 10,000 chars
  "voice":        "af_bella",         // optional, default af_bella
  "resume_index": 0                   // optional, for reconnection
}

You receive:

Audio format

To save as a WAV file (Python):

import struct

def pcm_to_wav(pcm: bytes, filename: str):
    sr, ch, bd = 24000, 1, 16
    with open(filename, "wb") as f:
        f.write(b"RIFF")
        f.write(struct.pack("<I", 36 + len(pcm)))
        f.write(b"WAVE")
        f.write(b"fmt ")
        f.write(struct.pack("<I", 16))
        f.write(struct.pack("<H", 1))
        f.write(struct.pack("<H", ch))
        f.write(struct.pack("<I", sr))
        f.write(struct.pack("<I", sr * ch * bd // 8))
        f.write(struct.pack("<H", ch * bd // 8))
        f.write(struct.pack("<H", bd))
        f.write(b"data")
        f.write(struct.pack("<I", len(pcm)))
        f.write(pcm)

pcm_to_wav(pcm_bytes, "output.wav")

Available voices

List voices programmatically: GET https://voice.knewcleus.app/v1/voices

Error codes

Errors arrive as JSON on the WebSocket before it closes:

{"type": "error", "code": "insufficient_credits", "message": "No credits remaining."}

Plans and limits

Overage on Studio: $0.015/min · Growth API: $0.018/min