synthesis

you can synthesize in three ways, depending on how soon you need the audio and whether it is a one-shot clip or an ongoing conversation: batch (create), streaming (stream), and sessions (session). all three come in a sync and an async form.

batch synthesis

create is the simplest path: send text, get an Audio object back (a ready-to-play 24 kHz mono WAV). reach for it whenever you can wait for the whole clip before playing it.

sync
async

from rumikai import Rumik

client = Rumik()
audio = client.speech.create(text="[happy] Namaste! Kaise hain aap?", model="muga")
audio.save("hello.wav")

import asyncio
from rumikai import AsyncRumik

async def main():
    async with AsyncRumik() as client:
        audio = await client.speech.create(
            text="[happy] Namaste! Kaise hain aap?", model="muga"
        )
        audio.save("hello.wav")

asyncio.run(main())

create(text, model="muga", ...). only text is required.

parameter	type	default	notes
`text`	`str`	required	the text to synthesize. empty text raises `ValueError`.
`model`	`str`	`"muga"`	`"muga"` or `"mulberry"`.
`description`	`str`	`None`	required for `mulberry`. natural-language voice description.
`speaker`	`str`	`None`	`mulberry` only, optional. a named voice, e.g. `"ira"`.
`temperature`	`float`	`None`	sampling temperature.
`top_p`	`float`	`None`	nucleus sampling.
`top_k`	`int`	`None`	top-k sampling.
`repetition_penalty`	`float`	`None`	penalize repeated tokens.
`max_new_tokens`	`int`	`None`	output length cap. raise it (up to `8192`) if long `mulberry` audio comes back truncated.
`timeout`	`float`	`None`	per-request timeout override, in seconds.
`extra_headers`	`dict`	`None`	extra HTTP headers for this request only.

steering by model: muga uses an inline tone tag ([happy], [sad], [excited], [angry], [whisper], or neutral); mulberry always takes a description, plus an optional named speaker. see prompting muga and prompting mulberry.

the audio object

create returns an Audio holding the WAV bytes and request metadata.

member	description
`save(path)`	write the audio to a `.wav` file.
`bytes(audio)`	the raw bytes (`__bytes__`).
`len(audio)`	number of bytes (`__len__`).
`.is_wav`	whether the bytes include a WAV header.
`.content_type`	the response content type.
`.request_id`	the server request id (from `x-request-id`).

create audio is always a WAV. streaming and session audio is raw PCM; use pcm_to_wav() or the built-in save() helpers to add a WAV header.

streaming

stream opens a websocket and hands you raw PCM (24 kHz mono 16-bit) as it is generated, so playback can start before the sentence finishes synthesizing. it returns a SpeechStream you iterate over inside a with block.

streaming needs the ws extra: pip install "rumik-ai[ws]".

sync
async

with client.speech.stream(text="Streaming in real time.", model="mulberry") as stream:
    for chunk in stream:      # raw PCM (24kHz mono 16-bit) as it's generated
        play(chunk)           # feed your audio device
# or: stream.save("out.wav")

async with client.speech.stream(text="Streaming in real time.", model="mulberry") as stream:
    async for chunk in stream:
        await play(chunk)

stream(text, model="muga", description=None, speaker=None, timeout=None, idle_timeout=30). idle_timeout closes the socket after that many seconds with no audio.

member	description
iterate	yields raw PCM chunks (`bytes`).
`.read()`	all remaining PCM as one `bytes` object.
`.save(path)`	drain the stream and write a WAV file.
`.request_id`	the server request id.
`.credits_used`	credits billed for the stream.

sessions and voice agents

a session keeps a single websocket open across a whole conversation. you send text, read back events as they arrive, and call interrupt() the moment the user starts talking over the agent. this is what you build a real-time voice agent on.

sessions need the ws extra: pip install "rumik-ai[ws]".

from rumikai import Rumik, AudioChunk, UtteranceDone

client = Rumik()
with client.speech.session(
    model="mulberry",
    description="a warm 30s female voice, smooth timbre, conversational pacing",
    speaker="ira",
) as session:
    session.send("Hello! How can I help you today?")
    for event in session:
        if isinstance(event, AudioChunk):
            play(event.data)
            if user_started_talking():        # barge-in
                session.interrupt()
                session.send("Sorry, go ahead.")
        elif isinstance(event, UtteranceDone):
            break

session(model="muga", description=None, speaker=None, timeout=None, idle_timeout=30) returns a SpeechSession, a context manager.

member	description
`send(text)`	synthesize a new utterance. sending again mid-utterance is a barge-in.
`interrupt()`	stop the current utterance immediately.
`close()`	end the session (or leave the `with` block).
iterate	yields session events as they arrive.
`iter_audio()`	yields only the PCM chunks, skipping control events.
`.last_request_id`	request id of the most recent utterance.
`.last_credits_used`	credits billed for the most recent utterance.

events yielded while iterating:

event	attributes	meaning
`AudioChunk`	`.data`	a raw PCM chunk (24 kHz mono 16-bit).
`UtteranceDone`	`.request_id`, `.credits_used`	the utterance finished normally.
`UtteranceCancelled`	`.request_id`, `.reason`	the utterance was stopped. `.reason` is `"interrupt"` (a new `send` replaced it) or `"cancel"` (you called `interrupt()`).

a session does not auto-reconnect if the socket drops. detect the error, open a new session, and resend. input is always whole utterances; there is no partial or streaming text input.

async

AsyncRumik is the same client with awaitable calls, so it drops straight into an async app. create, stream, and session all work with await, async with, and async for.

import asyncio
from rumikai import AsyncRumik

async def main():
    async with AsyncRumik() as client:
        clips = await asyncio.gather(
            client.speech.create(text="One"),
            client.speech.create(text="Two"),
            client.speech.create(text="Three"),
        )
        for i, audio in enumerate(clips):
            audio.save(f"clip_{i}.wav")

asyncio.run(main())

asyncio.gather runs requests in parallel over one shared connection pool. reuse a single AsyncRumik rather than one per request.

documentation

SDK

integrations

cookbook

API reference

batch synthesis

the audio object

streaming

sessions and voice agents

async

​batch synthesis

​the audio object

​streaming

​sessions and voice agents

​async

batch synthesis

the audio object

streaming

sessions and voice agents

async