AniwaffleDocsHomeContact our team
Developer preview. Public API access is not open yet. Contact our team to discuss integration.

Text to Speech

TTS API reference

Code examples

HTTP and WebSocket contracts for voices, synthesis, streaming events, audio output, errors, and production behavior.

Start here

Choose one-shot or streaming

Use HTTP one-shot when the complete text is ready. Use WebSocket streaming when text arrives incrementally or playback should begin before generation finishes. Both paths use the same voices, authentication, formats, and audit ledger.

Default region: United States

The default endpoints and examples use the US. Region selection affects API latency, especially the time to the first WebSocket audio chunk. For callers in Japan or nearby parts of Asia, the Japan endpoint can reduce network latency. Choose the region closest to the process making the API request; a backend calling TTS should use its own location.

For Japan, use https://jp.aniwaffle.com/v1/tts for HTTP or wss://jp.aniwaffle.com/v1/tts/stream for streaming. Direct TTS calls select the region by hostname, not a JSON field. See regional endpoints.

Region selection reduces the network portion of latency; synthesis time and queueing still depend on the request and current load. Compare WebSocket time to first audio separately from HTTP time to the complete audio response.

1. Authenticate

Send your workspace API key as a bearer token.

2. Choose a voice

List available Narya voice IDs and supported formats.

3. Synthesize

Use HTTP for one result or WebSocket for streamed chunks.

Before you begin

API keyAn Owner, Admin, or Builder creates it in the Dashboard sidebar under Config → Integrations. See Authentication below for every step.
Voice IDCall GET /v1/voices and use an id returned for the same workspace.
Server runtimeNode.js 20+ or Python 3.11+ for the examples below.
voice_id is the only synthesis choice

Send the Narya voice_id. Do not send model IDs, provider names, provider voice references, or routing policies; Narya resolves those server-side.

Environment setup

Endpoints and environment file

Select the TTS region through the hostname. Send HTTP requests and open WebSocket streams on the same regional host, with a key created in that environment's Dashboard.

EnvironmentHTTP base URLWebSocket endpoint
Production · UShttps://aniwaffle.comwss://aniwaffle.com/v1/tts/stream
Production · Japanhttps://jp.aniwaffle.comwss://jp.aniwaffle.com/v1/tts/stream
Development · UShttps://dev.aniwaffle.comwss://dev.aniwaffle.com/v1/tts/stream
Development · Japanhttps://dev.jp.aniwaffle.comwss://dev.jp.aniwaffle.com/v1/tts/stream

Use GET /v1/voices for voice discovery and POST /v1/tts for one-shot TTS. The TTS request body has no region field. For Waffle, the hostname selects the region only for realtime: true, which currently requires a mono voice and Japan; non-realtime requests use the same throughput pool from either hostname. Stereo realtime: true requests are rejected before synthesis or billing. Realtime and standard requests share the 20,000-character limit per request, including voice tags and all text events. Split longer text into separate requests; over-limit input is rejected before its synthesis. Audio already generated by earlier WebSocket flushes is billed normally. Within an environment, both regions accept the same workspace API key and voice IDs. DEV and PROD use separate keys.

Create your environment file

Keep the key on your backend. The examples below read these variables.

.env
NARYA_TTS_BASE_URL=https://aniwaffle.com
NARYA_TTS_WS_URL=wss://aniwaffle.com/v1/tts/stream
NARYA_TTS_API_KEY=awp_...

# Choose an exact voice from GET /v1/voices. This is a Narya ID, not an
# upstream provider reference. The examples derive its output format at runtime.
NARYA_VOICE_ID=your_narya_voice_id

For Japan production, set these two variables. All HTTP and WebSocket examples on this page use them. Leaving the values above unchanged uses the US; the service does not automatically choose the nearest region.

.env · Japan production
NARYA_TTS_BASE_URL=https://jp.aniwaffle.com
NARYA_TTS_WS_URL=wss://jp.aniwaffle.com/v1/tts/stream

Voice discovery

List the voices you can use

The list contains the voices this key can use. A saved voice ID that is no longer available to the workspace is rejected even if it was usable before; list voices again after a permission change. Voice IDs are stable Narya identifiers scoped to your workspace. The response intentionally does not expose upstream providers, models, or provider voice references.

GET /v1/voices
curl --request GET \
  --url "$NARYA_TTS_BASE_URL/v1/voices" \
  --header "Authorization: Bearer $NARYA_TTS_API_KEY"
200 · application/json · example response
{
  "voices": [
    {
      "id": "<voice-id-for-your-workspace>",
      "name": "Example voice",
      "output_formats": ["opus_48000_64", "pcm_16000", "pcm_44100"],
      "capabilities": ["tts", "voice_tags"],
      "nsfw": false
    }
  ]
}
FieldTypeRequiredDescription
voices[].idstringYesPass this Narya-owned value as voice_id to one-shot or streaming TTS.
voices[].namestringYesHuman-readable display name. Includes the model name when a voice has multiple routes; use the corresponding id to select that model.
voices[].output_formatsstring[]YesFormats this voice can deliver without provider-specific substitution.
voices[].capabilitiesstring[]YesFeatures supported by this exact voice variant. Check for voice_tags before sending expressive cues.
voices[].nsfwbooleanYesTrue when the voice is intended for adult content. Public-facing applications should filter these voices out unless the surface is explicitly age-gated.
Recommended default: opus_48000_64

Prefer opus_48000_64 for modern realtime transport when the selected voice lists it. It preserves full-band audio while reducing bandwidth. Prefer pcm_48000 for uncompressed PCM when the voice advertises it; use pcm_44100 or pcm_24000 for compatible lower-rate pipelines. Waffle voices support a minimum output rate of 24 kHz. Other providers may advertise pcm_16000 for a 16 kHz constraint. The quickstart derives the format from that exact voice and fails when none is available.

Do not copy provider voice IDs

A value from another TTS service is not a Narya voice_id. If a voice is absent here, it is not enabled for this key.

Example IDs are placeholders

This page does not define a universal preset voice. Copy an actual voices[].id from your authenticated response; never send the placeholder values shown in protocol examples.

5-minute quickstart

Make your first request

The examples discover the selected voice, prefer Opus when it supports Opus, and otherwise use its first advertised format before making one TTS request.

01

Discover

Choose an exact voice id from GET /v1/voices.

02

Send

Derive its format, then POST the TTS request.

03

Save

Write the response body as audio bytes.

curl · one-shot
# Requires jq. Fails if the exact voice is missing or advertises no formats.
output_format="$(curl --fail-with-body --silent --show-error \
  --url "$NARYA_TTS_BASE_URL/v1/voices" \
  --header "Authorization: Bearer $NARYA_TTS_API_KEY" \
  | jq --arg voice_id "$NARYA_VOICE_ID" --exit-status --raw-output '
      [.voices[] | select(.id == $voice_id)][0]
      | if . == null then error("Selected voice not found")
        elif (.output_formats | index("opus_48000_64")) != null then "opus_48000_64"
        elif (.output_formats | length) > 0 then .output_formats[0]
        else error("Selected voice has no output_formats")
        end
    ')"
test -n "$output_format" || { echo "Could not select an output format" >&2; exit 1; }

curl --fail-with-body --request POST \
  --url "$NARYA_TTS_BASE_URL/v1/tts" \
  --header "Authorization: Bearer $NARYA_TTS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "Hello from Narya.",
    "voice_id": "'"$NARYA_VOICE_ID"'",
    "output_format": "'"$output_format"'"
  }' \
  --dump-header response-headers.txt \
  --output output.audio
oneshot.ts
import { writeFile } from 'node:fs/promises'

const baseUrl = process.env.NARYA_TTS_BASE_URL
const apiKey = process.env.NARYA_TTS_API_KEY
const voiceId = process.env.NARYA_VOICE_ID
if (!baseUrl || !apiKey || !voiceId) throw new Error('Missing Narya environment variables')

const voicesResponse = await fetch(`${baseUrl}/v1/voices`, {
  headers: { Authorization: `Bearer ${apiKey}` },
})
if (!voicesResponse.ok) throw new Error(`Voice discovery failed: ${voicesResponse.status}`)
const { voices } = await voicesResponse.json() as {
  voices: Array<{ id: string; output_formats: string[] }>
}
const voice = voices.find((candidate) => candidate.id === voiceId)
if (!voice) throw new Error(`Voice not found: ${voiceId}`)
const outputFormat = voice.output_formats.includes('opus_48000_64')
  ? 'opus_48000_64'
  : voice.output_formats[0]
if (!outputFormat) throw new Error(`Voice has no output formats: ${voiceId}`)

const response = await fetch(`${baseUrl}/v1/tts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Hello from Narya.',
    voice_id: voiceId,
    output_format: outputFormat,
  }),
})
if (!response.ok) throw new Error(`Narya TTS failed: ${response.status} ${await response.text()}`)

await writeFile('output.audio', Buffer.from(await response.arrayBuffer()))
console.log('request', response.headers.get('x-request-id'))
console.log('audit', response.headers.get('x-audit-id'))
Retry one-shot requests safely

Send an optional Idempotency-Key header (1–200 characters) with POST /v1/tts. Reuse it only for the same request body and credentials. A successful retry returns the original audio and request/audit IDs without another synthesis or charge, for 24 hours. Replays still require current workspace and voice access, but do not need a fresh credit balance. A running duplicate returns HTTP 409 with Retry-After; a different body using the same key also returns 409. Expired, failed or unavailable results return HTTP 410. An expired key never starts another charge; use a new key for a new request. Requests without this header remain separate operations.

Expected result

The command prints an audit ID and writes output.audio. Use X-Audio-Format to choose the decoder or final filename. An HTTP error returns the same structured error fields used by streaming.

Framework guide

External Pipecat integration

Use a small TTSService adapter when Pipecat owns transport, turn-taking, interruption, and playback. The adapter below converts Narya audio events into the raw PCM frames Pipecat expects.

1. Request PCM

Ask Narya for pcm_44100 so no compressed decoder sits in the realtime path.

2. Validate delivery

Require event.format to match the sample-rate-qualified PCM format you requested.

3. Match playback

Set PipelineParams.audio_out_sample_rate to the TTS service sample rate.

install
python -m pip install "pipecat-ai==1.4.0" "websockets>=15,<17"
narya_tts_service.py
import base64
import json
import uuid
from collections.abc import AsyncGenerator

from pipecat.frames.frames import ErrorFrame, Frame, TTSAudioRawFrame, TTSStartedFrame, TTSStoppedFrame
from pipecat.services.settings import TTSSettings
from pipecat.services.tts_service import TTSService
from websockets.asyncio.client import connect


class NaryaTTSService(TTSService):
    def __init__(self, *, endpoint: str, api_key: str, voice_id: str, sample_rate: int = 44100, **kwargs) -> None:
        super().__init__(
            sample_rate=sample_rate,
            settings=TTSSettings(model="narya", voice=voice_id, language=None),
            **kwargs,
        )
        self.endpoint = endpoint
        self.api_key = api_key
        self.voice_id = voice_id
        self.sample_rate = sample_rate
        self.partner_session_id = f"pipecat_{uuid.uuid4()}"

    async def run_tts(self, text: str, context_id: str) -> AsyncGenerator[Frame | None, None]:
        yield TTSStartedFrame()
        try:
            async with connect(
                self.endpoint,
                additional_headers={"Authorization": f"Bearer {self.api_key}"},
                open_timeout=10,
                max_size=None,
            ) as websocket:
                await websocket.send(json.dumps({
                    "event": "start",
                    "request": {
                        "partner_session_id": self.partner_session_id,
                        "context_id": context_id,
                        "voice_id": self.voice_id,
                        "output_format": f"pcm_{self.sample_rate}",
                    },
                }))
                await websocket.send(json.dumps({"event": "text", "text": text}))
                await websocket.send(json.dumps({"event": "stop"}))

                async for raw in websocket:
                    event = json.loads(raw)
                    if event["event"] == "audio":
                        expected = f"pcm_{self.sample_rate}"
                        if event["format"] != expected:
                            raise ValueError(f"Expected {expected}, got {event['format']}")
                        yield TTSAudioRawFrame(
                            audio=base64.b64decode(event["audio"]),
                            sample_rate=self.sample_rate,
                            num_channels=1,
                            context_id=context_id,
                        )
                    elif event["event"] == "error":
                        yield ErrorFrame(error=f"narya_tts_error:{event['code']}")
                        break
                    elif event["event"] == "finish":
                        break
        except Exception as error:
            yield ErrorFrame(error=f"narya_tts_transport_error:{error}")
        yield TTSStoppedFrame()
pipeline wiring
import os

from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker

# transport, stt, llm, and context_aggregator come from your existing bot.
output_sample_rate = int(os.getenv("NARYA_TTS_SAMPLE_RATE", "44100"))
tts = NaryaTTSService(
    endpoint=os.environ["NARYA_TTS_WS_URL"],
    api_key=os.environ["NARYA_TTS_API_KEY"],
    voice_id=os.environ["NARYA_VOICE_ID"],
    sample_rate=output_sample_rate,
)

pipeline = Pipeline([
    transport.input(), stt, context_aggregator.user(), llm,
    tts, transport.output(), context_aggregator.assistant(),
])
worker = PipelineWorker(
    pipeline,
    params=PipelineParams(
        audio_in_sample_rate=16000,
        audio_out_sample_rate=output_sample_rate,
        enable_metrics=True,
        enable_usage_metrics=True,
    ),
)
Require an explicit PCM sample rate

TTSAudioRawFrame carries decoded PCM. Accept pcm_<sample-rate> or inspect a WAV header. Reject bare pcm because its sample rate is ambiguous; decode compressed audio before creating the frame.

Keep the API key in the bot process

The Pipecat server sends the bearer header during the WebSocket upgrade. Never forward the permanent key to the browser transport or include it in RTVI client parameters.

Security

Authentication and access

Authenticate during the WebSocket upgrade. Permanent keys belong only in trusted server environments.

Server-to-server

Send the key as a bearer token in the WebSocket upgrade request. Store it in your secret manager and rotate it through the Dashboard.

Authorization: Bearer awp_...

Browser or mobile

Never embed a permanent key in a website or app bundle. Your trusted backend either proxies TTS itself, or mints a short-lived streaming token (below) and hands only that token to the client.

Short-lived streaming tokens

Your backend can call POST /v1/tts/stream-tokens with the workspace key to receive { token, expires_at, websocket_url, capabilities }. The token is valid for 2 minutes, opens /v1/tts/streamconnections (as ?token= or a bearer header) until it expires, and never exposes the permanent key. Mint one token per connection and treat it as single-use even though reuse inside the 2-minute window is not rejected. Browser connections are additionally checked against a platform Origin allowlist — ask Narya to allowlist your web origin before shipping a browser client.

Create a production key

  1. 1Open the production Dashboard and sign in. Creating keys requires a workspace Owner, Admin, or Builder role.
  2. 2Select Integrations in the sidebar (under the Config group). The page is titled API keys.
  3. 3Enter a descriptive Label such as checkout-voice-prod and select Create key.
  4. 4Copy the full awp_ value from the "Key created. Copy it now, it won't be shown again." banner. Only its hash is retained.
  5. 5Transfer it through your approved secret-sharing channel and store it server-side. Revoke compromised keys from the Issued keys list. Revoked keys are rejected on new HTTP requests and new WebSocket handshakes. An already-authenticated public TTS WebSocket remains authorized for its single synthesis request, even if start is sent after revocation; revocation does not close that connection.
Open production Dashboard

HTTP guide

One-shot TTS

POST one complete text input and receive audio bytes directly in the response body. Use this for notifications, prerecorded prompts, previews, and any request where the full text is already available.

Node.js 20+
import { writeFile } from 'node:fs/promises'

const baseUrl = process.env.NARYA_TTS_BASE_URL
const apiKey = process.env.NARYA_TTS_API_KEY
const voiceId = process.env.NARYA_VOICE_ID
if (!baseUrl || !apiKey || !voiceId) throw new Error('Missing Narya environment variables')

const voicesResponse = await fetch(`${baseUrl}/v1/voices`, {
  headers: { Authorization: `Bearer ${apiKey}` },
})
if (!voicesResponse.ok) throw new Error(`Voice discovery failed: ${voicesResponse.status}`)
const { voices } = await voicesResponse.json() as {
  voices: Array<{ id: string; output_formats: string[] }>
}
const voice = voices.find((candidate) => candidate.id === voiceId)
if (!voice) throw new Error(`Voice not found: ${voiceId}`)
const outputFormat = voice.output_formats.includes('opus_48000_64')
  ? 'opus_48000_64'
  : voice.output_formats[0]
if (!outputFormat) throw new Error(`Voice has no output formats: ${voiceId}`)

const response = await fetch(`${baseUrl}/v1/tts`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Hello from Narya.',
    voice_id: voiceId,
    output_format: outputFormat,
  }),
})
if (!response.ok) throw new Error(`Narya TTS failed: ${response.status} ${await response.text()}`)

await writeFile('output.audio', Buffer.from(await response.arrayBuffer()))
console.log('request', response.headers.get('x-request-id'))
console.log('audit', response.headers.get('x-audit-id'))
FieldTypeRequiredDescription
textstringYesComplete UTF-8 text, 1 to 20,000 characters. Emotion tags go inline; see Emotion tags.
voice_idstringYesNarya voice ID returned by GET /v1/voices.
output_formatenumYesA format listed for this voice.
realtimebooleanNoDefaults to false. Waffle TTS only: selects the realtime tier at 2× the standard price. Realtime requests use the Japan latency pool and require the Japan endpoint. Standard requests use the throughput pool from either endpoint.
channels1 or 2NoDefaults to 1. Stereo requires 2, a voice with the stereo capability, and PCM output.
partner_session_idstringNoOptional external correlation ID. Omit it when you do not have one.
context_idstringNoYour turn or playback-context ID.
params.speedpositive numberNoSpeaking-speed multiplier when supported by the selected voice.
response bodyHTTP 200

Raw audio bytes. Use Content-Type and X-Audio-Format to select the decoder or filename.

response headersHTTP 200

X-Request-Id, X-Audit-Id, X-Audio-Format, X-Audio-Channels, and X-Audio-Duration-Ms. The duration header describes encoded playback. Public Waffle TTS costs 200 credits/hour of generated audio, or 400 credits/hour with realtime: true. Other providers charge supplier model cost; matching Workspace BYOK requests record usage without deducting credits. The model call audit retains the supplier usage and settlement status.

Errors are JSON, not audio

For non-2xx responses, parse the JSON error object and use its retryable value. Do not save an error body as an audio file.

Long-form audio

Submit long text and collect the result later

POST /v1/tts/jobs accepts the same JSON body and text limit as POST /v1/tts, with a required Idempotency-Key header (1–200 characters). It returns HTTP 202 after saving the job; the connection does not stay open while audio is generated. Synchronous HTTP and WebSocket behavior remain unchanged.

Code
{
  "id": "<job-id>",
  "request_id": "rq_<request-id>",
  "status": "queued",
  "expires_at": "2026-11-12T00:00:00.000Z",
  "status_url": "/v1/tts/jobs/<job-id>",
  "audio_url": null
}

Poll GET /v1/tts/jobs/<job-id> using the same environment. Status is queued, running, completed, failed, or expired. When completed, audio_url points to GET /v1/tts/jobs/<job-id>/audio. This returns the original audio bytes and the same X-Request-Id, X-Audit-Id, audio format, channel count, and duration headers as synchronous synthesis. Repeated downloads do not synthesize or charge again. Use a valid workspace API key for every call; another workspace cannot query or download the job. Downloads still require current workspace and voice access, but no fresh credit balance.

Reuse the same submission key and body after a lost response: it returns the same job ID. A changed body returns 409. The submission key is scoped to the workspace and API-key identity; save the returned job ID before rotating the submitting key. A replacement key in the same workspace can query and download that ID. There can be at most 20 queued or running jobs per workspace; excess submissions return 429 and Retry-After: 10. These limits bound the queue and do not promise 20 simultaneous syntheses.

Jobs and their downloadable results expire 24 hours after submission. Downloading before completion returns 409 and Retry-After: 2; a failed, expired, or missing result returns 410. A failed job includes error_code: "synthesis_failed". The same key remains reserved after failure or expiry. An intentional new attempt requires a new key.

Queued jobs survive restarts. Ordinary releases drain active synthesis. If a process is forcibly interrupted after dispatch, the job becomes failed after reconciliation; it is never automatically synthesized again. Audio already generated at the provider may still incur provider cost. This API avoids holding an HTTP connection open during generation; it does not shorten synthesis time or resume interrupted synthesis. Revoking the submitting key before dispatch prevents that queued synthesis.

Code
import { WaffleServer } from '@aniwaffle/server'
import { setTimeout } from 'node:timers/promises'
import { Readable } from 'node:stream'
import { pipeline } from 'node:stream/promises'
import { createWriteStream } from 'node:fs'

const waffle = new WaffleServer({ apiKey: process.env.WAFFLE_API_KEY!, region: 'jp' })
let job = await waffle.createTtsJob({
  text: 'Your complete long-form text.',
  voice_id: '<voice-id>',
  output_format: 'pcm_48000',
}, 'unique-document-revision')
while (job.status === 'queued' || job.status === 'running') {
  await setTimeout(2_000)
  job = await waffle.getTtsJob(job.id)
}
if (job.status !== 'completed') throw new Error(`Synthesis ${job.status}`)
const audio = await waffle.getTtsJobAudio(job.id, { timeoutMs: 600_000 })
await pipeline(Readable.fromWeb(audio.body!), createWriteStream('speech.pcm'))

The download deadline covers the complete transfer. Choose it for the expected file size and network rate; cancel the response body if abandoning the download. Avoid buffering long audio in memory.

Resume an interrupted download

Save the job ID, strong ETag from the download response, and the number of bytes actually written to disk. Request the same audio URL with Range: bytes=<saved-bytes>- and If-Range: <saved-etag>. This uses ordinary Fetch; no client library upgrade is required.

Code
const audio = await fetch(`${apiOrigin}/v1/tts/jobs/${jobId}/audio`, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    Range: `bytes=${savedBytes}-`,
    'If-Range': savedEtag,
  },
  signal: AbortSignal.timeout(600_000),
})
if (audio.status !== 200 && audio.status !== 206) throw new Error(`Download ${audio.status}`)
if (audio.status === 206 && !audio.headers.get('content-range')?.startsWith(`bytes ${savedBytes}-`)) {
  await audio.body?.cancel()
  throw new Error('Unexpected download offset')
}
// Persist this ETag with jobId before writing; on failure retain the actual file size.
const etag = audio.headers.get('etag')!
await pipeline(Readable.fromWeb(audio.body!), createWriteStream('speech.pcm', {
  flags: audio.status === 206 ? 'a' : 'w',
}))

206 contains only the requested bytes; check Content-Range before appending. 200 means a complete representation, so replace the local file (an unmatched, weak, or date-form If-Range also returns 200). Verify the final file size against the total in Content-Range, or Content-Length for 200. 416 includes Content-Range: bytes */<total>; only treat an already saved file as complete when its ETag and length also match. Otherwise restart the download.

Single closed (bytes=0-1023), open (bytes=1024-), and suffix (bytes=-1024) ranges are supported. Invalid or multiple ranges are ignored and return 200. Every download still checks workspace, key, voice, and expiry; 401/403/404/410 are not a reason to resubmit synthesis. Resume before the original 24-hour expiry. Downloads do not add another synthesis, charge, or history entry.

Expressive speech

Emotion tags

Put emotion, delivery, and human-sound tags inline in text. They work the same way for one-shot and streaming requests. Tag effects vary by voice; listen before relying on them in production.

Tags live in the text

Wrap a span with a paired tag, such as <happy>Hello.</happy>, and insert a single sound with [laughing]. Check voices[].capabilities for voice_tags before sending tags. When a voice does not support tags, Narya removes them and speaks the remaining text.

one-shot · tagged text
{
  "text": "<happy>I am happy to see you today.</happy> [laughing]",
  "voice_id": "<voice-id-from-get-v1-voices>",
  "output_format": "pcm_24000"
}
one-shot · sound only
{
  "text": "[panting] [gasping]",
  "voice_id": "<voice-id-from-get-v1-voices>",
  "output_format": "pcm_24000"
}
Streaming uses the same syntax

Send tags inside text events. Keep each paired span balanced before the next flush or stop.

streaming · text event
{
  "event": "text",
  "text": "<whispering>Come closer.</whispering> [sighing]"
}

waffle 0.1 1101 beta

Waffle supports a fixed vocabulary of emotion, delivery, and nonverbal controls. In Playground, type [ or < for completion, or use the Tags menu and Auto Tag. Emotion and delivery controls are inserted as pairs around selected text (or the rest of the paragraph). Click any tag to choose from all available tags. Invalid combinations show a validation message before generation. API bracket emotion/delivery cues remain supported: each cue applies until the next cue of the same type or the end. Narya converts these to paired spans with emotion outside delivery.

Waffle voices

Emotions

happysadangryafraiddisgustedsurprisedembarrassedaroused

Delivery

whisperingshouting

Human sounds

sighinggaspingpantingsniffinglaughinggroaningcryingcoughinglicking
<happy><whispering>Hello.</whispering></happy> [laughing]
Put emotion outside delivery when you nest paired spans. Use either native paired spans or bracket emotion/delivery cues in a request, not both. Human sounds work with either form, including sound-only text. Unknown tags, unbalanced spans, and incorrectly nested spans return invalid_request. Escape literal \\, [ or < with a backslash.
Practical starting point

Begin with one primary cue and test the exact voice. Unknown or unsupported controls return invalid_request; voices without tag support strip the known control syntax and speak only the remaining text.

Protocol guide

Connection lifecycle

A WebSocket carries exactly one synthesis request. Control messages are JSON text frames; audio is returned inside JSON events as base64.

Public awp_ keys are authenticated at the WebSocket handshake. Revoking a key blocks new requests and connections, including reconnects, but an existing authenticated connection can still start or finish its single synthesis request. This is the supported revocation boundary.

  1. 1ClientconnectOpen the production WSS endpoint with the bearer token. A rejected credential fails the WebSocket handshake itself with HTTP 401 — the connection never upgrades, so no error event is delivered.
  2. 2ClientstartDeclare attribution, the Narya voice ID, and output format exactly once. Narya assigns the request ID and returns it on server events.
  3. 3ClienttextSend one or more non-empty text segments unless this is a tag-only request. Segments are appended in wire order.
  4. 4ClientflushOptional. Synthesize the current buffer now and keep the request open for more text.
  5. 5ServeraudioReceive zero or more ordered chunks. The first sequence number is 1.
  6. 6ClientstopSynthesize any remaining text, or a tag-only request, and finalize the request.
  7. 7Serverusage → finishRead the terminal metadata, then allow the server to close normally. An error replaces finish when the request fails.
Valid ordering

start → (text+ → (flush → text+)*)? → stop

Terminal events

Treat finish or error as final. Do not send more control events afterward.

Low-latency input

Stream text without hurting prosody

Use flush at natural phrase boundaries when text arrives incrementally. This starts synthesis without ending the request.

json lines · after start
{"event":"text","text":"Your order is ready, "}
{"event":"flush"}
{"event":"text","text":"and it will arrive tomorrow."}
{"event":"stop"}

Flush complete phrases

Prefer clauses or sentences over individual LLM tokens. Include spaces and punctuation in the text exactly where they should be spoken.

Balance latency and context

Smaller flushes can reduce time to first audio but give the model less linguistic context. Begin with sentence boundaries, then tune using measured playback latency.

  • Each text event may contain at most 5,000 characters.
  • The production request limit is 20,000 characters across all text events.
  • An empty buffer on flush is a no-op.
  • stop flushes the remaining buffer or starts tag-only synthesis; a separate final flush is unnecessary.
  • Open a new WebSocket for the next utterance; Narya assigns it a new request ID.

Playback guide

Handle audio output correctly

Every audio event includes the delivered format. Decode base64, preserve sequence order, and route chunks using the request or context ID.

server · audio event
{
  "event": "audio",
  "request_id": "rq_018f...",
  "context_id": "assistant_turn_7",
  "seq": 1,
  "audio": "AAABAAIA...",
  "format": "pcm_44100"
}
Requested formatNominal encodingTypical use
pcm_16000Raw 16-bit PCM · 16 kHzExplicitly 16 kHz-constrained pipelines
pcm_24000Raw 16-bit PCM · 24 kHzVoice-agent pipelines standardized on 24 kHz
pcm_44100Raw 16-bit PCM · 44.1 kHzRaw PCM compatibility and decoder-free pipelines
pcm_48000Raw 16-bit PCM · 48 kHzNative-rate Waffle audio and decoder-free realtime pipelines
aac_44100_128AAC · 44.1 kHz · 128 kbpsMobile and media pipelines
opus_48000_64Ogg Opus · 48 kHz · 64 kbpsRecommended default for modern realtime transport
The event format is authoritative

Inspect event.format for every request and reject unexpected values. Narya does not silently substitute a different format for a voice.

Playback rules

  • WebSocket messages arrive in order; still use seq to detect missing or duplicated application-level chunks.
  • Compressed chunks can be concatenated only when your decoder supports the delivered stream format.
  • Raw PCM has no container header. Add the appropriate WAV header only when a file or player requires one.
  • opus_48000_64 is the recommended default when the selected voice supports it; decode the delivered Ogg Opus stream at 48 kHz.
  • PCM defaults to mono and is signed 16-bit little-endian; the numeric suffix is its sample rate. pcm_48000 plays at 48,000 Hz, pcm_44100 at 44,100 Hz, and pcm_24000 at 24,000 Hz. PCM16 describes bit depth, not a 16 kHz rate. Waffle streams at these three rates and rejects pcm_16000.
  • Stereo PCM interleaves complete sample frames: L0, R0, L1, R1, .... Each stereo frame is four bytes. Duration in seconds is byteLength / (sampleRate * channels * 2). Preserve both channels when resampling and playing audio.
  • If you explicitly send channels, each audio event echoes it. For legacy requests that omit it, audio events keep their original shape and mean mono. Reject any change in format or channel count within a stream.
  • Treat bare pcm as invalid because it does not identify a sample rate. Never infer it from the requested format.
  • Do not mark playback complete when the socket closes; mark synthesis complete on finish.

Native stereo PCM

Use a voice_id whose catalog entry includes stereo, and request channels: 2. The endpoints stay the same. Unsupported voices or compressed stereo return an error. Omitting channels continues to mean mono; a dedicated stereo voice requires an explicit stereo request.

Code
{"event":"start","request":{"voice_id":"<stereo-voice-id>","output_format":"pcm_48000","channels":2}}
Code
{"event":"audio","request_id":"rq_example","seq":1,"format":"pcm_48000","channels":2,"audio":"6AMY/NAHMPg="}

The example bytes are e8 03 18 fc d0 07 30 f8: two frames, (L=1000, R=-1000) and (L=2000, R=-2000). They are headerless PCM, not a WAV file.

For HTTP, send {"text":"Hello.","voice_id":"<stereo-voice-id>","output_format":"pcm_48000","channels":2} to POST /v1/tts. The response includes X-Audio-Channels: 2 and Content-Type: audio/pcm;rate=48000;channels=2. Use a new Idempotency-Key when changing the channel count.

Waffle Stereo 0.1 Beta (waffle:0.1-stereo-beta) supports paired position tags: <center>, <left:near>, <left:far>, <right:near>, and <right:far>. Position wraps emotion, which wraps delivery: <left:near><happy><whispering>Hello.</whispering></happy></left:near>. These tags are available only on the stereo model. Initial stereo output supports PCM at 24, 44.1 and 48 kHz; availability is determined by the selected environment's voice catalog.

Production guide

Production readiness checklist

A production client needs explicit timeout, retry, observability, and playback decisions around the basic protocol.

Secrets

Keep permanent keys in a server-side secret manager; never log or ship them.

Timeouts

Set a connection timeout and a terminal-event timeout appropriate to your utterance length. The 30-second timeouts in the examples suit short utterances. For longer text, allow enough total time for synthesis and track gaps between audio events separately; receiving audio does not mean the request has finished. HTTP returns the completed audio, so its response deadline must cover the entire synthesis.

Identifiers

Log the returned request_id with partner_session_id, context_id, and audit_id.

Retry budget

Retry only retryable errors with exponential backoff and jitter.

Replay safety

Prevent completed or partially played speech from replaying unintentionally.

Backpressure

Bound decoded audio queues so slow playback cannot grow memory without limit.

Cancellation

Close the WebSocket when the user interrupts; do not automatically replay cancelled speech.

Format validation

Select decoding from event.format and test every format enabled for your workspace.

API reference

Start request

The first control frame declares the complete request configuration. Send start exactly once per connection.

client · start event
{
  "event": "start",
  "request": {
    "partner_session_id": "conversation_42",
    "context_id": "assistant_turn_7",
    "voice_id": "<voice-id-returned-by-GET-/v1/voices>",
    "output_format": "pcm_44100"
  }
}
FieldTypeRequiredDescription
event"start"YesDiscriminator for the first control event.
request.partner_session_idstringNoOptional external audit correlation ID, 1–200 characters. It never owns billing or idempotency.
request.context_idstringNoYour turn, message, or playback-context ID. Echoed on audio events when supplied.
request.voice_idstringYesNarya voice identifier returned by GET /v1/voices.
request.output_formatenumYesRequested audio format. See Handle audio output.
request.realtimebooleanNoDefaults to false. Waffle TTS only: selects the realtime tier at 2× the standard price. Realtime requests use the Japan latency pool and require the Japan endpoint. Standard requests use the throughput pool from either endpoint.
request.channels1 or 2NoDefaults to 1. Use 2 with a stereo-capable voice and PCM output.
request.params.speedpositive numberNoOptional speaking-speed multiplier when supported by the selected voice.
request_id is server-owned

Do not send a request ID in start. Narya generates a UUID-based ID for every connection and includes it in every audio, usage, finish, or error event. It owns Narya billing and idempotency. Log it for support, but do not supply or reuse it as a client retry key.

API reference

Client events

After start, send text and optional flush events, then one stop event. All client messages must be JSON text frames.

text1 or more

Adds a non-empty text string to the current buffer. Maximum 5,000 characters per event.

flushoptional

Synthesizes the current buffer and keeps the request open. Has no additional fields.

stopexactly once

Synthesizes remaining text, emits terminal metadata, and ends the request.

FieldTypeRequiredDescription
text.event"text"YesText-event discriminator.
text.textstringYesNon-empty UTF-8 text, at most 5,000 characters.
flush.event"flush"YesFlush-event discriminator. No other fields.
stop.event"stop"YesStop-event discriminator. No other fields.

API reference

Server events

A successful request emits audio events, then usage and finish. A failed request emits one terminal error instead of finish.

audio0 or more

Base64 audio bytes plus request ID, optional context ID, one-based sequence number, and delivered format.

usageonce on success

Character and generated-audio totals plus the Narya voice ID.

finishterminal success

Final reason, credits used, settlement status, audit ID, and persistence status. cost.settlement_status: "pending" means the displayed credits are not final; missing supplier usage must be reconciled. Public Waffle TTS uses generated audio duration: 200 credits/hour for standard requests and 400 credits/hour for realtime: true. Other providers use the supplier's model cost without markup, converted at 1 USD = 1,000 credits, with the rate frozen when the request starts. Workspace BYOK for the selected provider/model records usage and deducts zero model credits. Each request rounds its charge once to 0.001 credit. Actual supplier usage from retries or cancellation can incur cost; missing supplier evidence stays pending for reconciliation. Saved audio playback and replay of a completed idempotent request create no new charge. Workspace Settings → Model call audit shows usage, outcome and settlement, including zero-credit calls. Historical requests retain their original tariff. The legacy amount, currency, and pass_through fields remain for v1 compatibility; amount is a deprecated USD projection (credits / 1000).

errorterminal failure

Stable code, optional detail, and the retryability decision for this failure.

server · usage
{
  "event": "usage",
  "request_id": "rq_018f...",
  "usage": { "chars": 48, "audio_ms": 2760 },
  "voice_id": "<voice-id-returned-by-GET-/v1/voices>"
}
server · finish
{
  "event": "finish",
  "request_id": "rq_018f...",
  "reason": "stop",
  "cost": { "credits": 0.153, "amount": 0.000153, "currency": "USD", "pass_through": true },
  "audit_id": "rq_018f...",
  "audio_persisted": true
}
server · error
{
  "event": "error",
  "request_id": "rq_018f...",
  "code": "provider_unavailable",
  "retryable": true,
  "detail": "The requested voice is temporarily unavailable."
}
FieldTypeRequiredDescription
audio.seqintegerAudioOne-based chunk sequence across the complete request, including multiple flushes.
audio.audiobase64 stringAudioEncoded bytes for this chunk.
audio.formatstringAudioDelivered wire format. Use this value to choose the decoder.
usage.usage.charsintegerUsageCharacters synthesized successfully across all segments.
usage.usage.audio_msintegerUsageGenerated media duration in milliseconds. Supplier billable usage is retained in the model call audit; historical requests keep their frozen tariff.
finish.audit_idstringFinishAudit correlation ID to include in support requests.
finish.audio_persistedbooleanFinishTrue after the audio object and recoverable history metadata are saved. Central Audit indexing may appear shortly afterward. Storage failure returns an error rather than a successful finish.
error.retryablebooleanErrorAuthoritative signal for whether a new attempt is safe.

Reliability reference

Errors, retries, and limits

Use the error event for application decisions and the WebSocket close code for transport diagnostics.

CodeRetry?Client action
unauthorizedNoCorrect, rotate, or re-scope the credential before reconnecting.
invalid_requestNoFix JSON, event order, configuration, or input limits.
invalid_voiceNoThe voice is unavailable for this workspace (HTTP 400 on one-shot). Refresh GET /v1/voices and choose an enabled, ready voice; do not retry the same unavailable ID.
unsupported_output_formatNoThe selected voice cannot produce this format (HTTP 400 on one-shot). Choose a format returned for that voice by GET /v1/voices.
provider_auth_missingNoContact Narya or use an approved configured fallback.
provider_unavailableIf retryable=trueOpen a new connection after exponential backoff with jitter.
provider_errorIf retryable=trueRetry only when explicitly allowed; otherwise escalate with the audit ID.
rate_limitedYes, after backoffRequest or unconfirmed-usage capacity is temporarily full (HTTP 429 on one-shot). Open a new request after exponential backoff with jitter. This is not a provider failure.
insufficient_creditNoThe workspace has insufficient credits (HTTP 402 on one-shot). Contact Narya to arrange additional credits before retrying.
organization_suspendedNoThe workspace is suspended (HTTP 403). Contact Narya.
capability_disabledNoTTS is not enabled for this workspace (HTTP 403). Contact Narya.
organization_account_missingNoWorkspace billing account is not provisioned (HTTP 503). Contact Narya.

Retry contract

A retry is a new connection, and Narya assigns it a new request_id. Keep the same partner_session_id only when it remains part of the same conversation. Never replay audio after a finish event.

Close codes

1008 means a malformed control frame — binary data or invalid JSON. Rejected credentials fail the handshake with HTTP 401 instead. 1009 means the control frame exceeded 64 KiB. A successful request closes normally after finish.

Partial audio may already have played

A retryable failure can occur after one or more audio chunks. Your application must decide whether to discard, resume at a product-safe boundary, or replace the utterance; blindly replaying the full request can duplicate speech for the listener.

Release history

Changelog

Contract changes are versioned here so integrations can distinguish additive capabilities from migrations that require client work.

v1.10.1

No change for TTS API requests. This release changed only internal credit reporting for Japan-region conversational speech.

v1.10.0

Added optional boolean `realtime` to HTTP request bodies and WebSocket `start.request`. It defaults to `false`. Both tiers currently use the shared inference pool. The API records the tier for billing; dedicated latency-priority routing is not yet enabled. Realtime costs twice the standard generated-audio tariff. Other providers reject `realtime: true`. Changing priority requires a new `Idempotency-Key`.

v1.9.0

Deprecation
  • Deprecated params.voice_tags on one-shot and streaming requests. It is still accepted but ignored; put tags inline in text instead.
  • One-shot text must now contain at least one character. For a sound-only request, send the tag as text, such as [laughing].

v1.6.0

Added `pcm_48000` to HTTP and WebSocket request schemas. Waffle supports 24, 44.1 and 48 kHz PCM; choose from the selected voice’s advertised `output_formats`. Waffle audio is emitted incrementally during generation.

v1.5.0

Additive
  • Added voices[].nsfw so public-facing applications can filter adult-content voices.
  • Added the pcm_24000 output format for 24 kHz voice-agent pipelines.

v1.4.0

Capability
  • Added voices[].capabilities so clients can identify exact variants with voice-tag support.
  • Made tag compatibility model specific.
  • Unsupported variants now omit structured and inline cues; tag-only requests remain invalid.

v1.3.0

Additive
  • Added optional params.voice_tags to one-shot and streaming requests.
  • Added tag-only synthesis by sending text: "" with at least one voice tag.
  • Added server-side tag syntax conversion and explicit model compatibility errors.

v1.2.0

Contract
  • Made request_id server-owned for every one-shot and streaming request.

v1.1.0

Endpoints
  • Added POST /v1/tts and GET /v1/voices with provider-neutral voice IDs.

v1.0.0

Initial
  • Published the initial authenticated WebSocket streaming contract.

Complete example

Node.js / TypeScript

This production-oriented Node.js client adds timeouts, sequence-aware assembly, delivered-format handling, and terminal-state checks.

install
npm install ws
npm install --save-dev tsx typescript @types/ws
stream.ts
import { randomUUID } from 'node:crypto'
import { writeFile } from 'node:fs/promises'
import WebSocket from 'ws'

const required = (name: string) => {
  const value = process.env[name]
  if (!value) throw new Error(`Missing environment variable: ${name}`)
  return value
}
const baseUrl = required('NARYA_TTS_BASE_URL')
const apiKey = required('NARYA_TTS_API_KEY')
const voiceId = required('NARYA_VOICE_ID')
const voicesResponse = await fetch(`${baseUrl}/v1/voices`, {
  headers: { Authorization: `Bearer ${apiKey}` },
})
if (!voicesResponse.ok) throw new Error(`Voice discovery failed: ${voicesResponse.status}`)
const { voices } = await voicesResponse.json() as {
  voices: Array<{ id: string; output_formats: string[] }>
}
const voice = voices.find((candidate) => candidate.id === voiceId)
if (!voice) throw new Error(`Voice not found: ${voiceId}`)
const selectedFormat = voice.output_formats.includes('opus_48000_64')
  ? 'opus_48000_64'
  : voice.output_formats[0]
if (!selectedFormat) throw new Error(`Voice has no output formats: ${voiceId}`)

const ws = new WebSocket(required('NARYA_TTS_WS_URL'), {
  headers: { Authorization: `Bearer ${apiKey}` },
  handshakeTimeout: 10_000,
})
const chunks = new Map<number, Buffer>()
let format = selectedFormat
let completed = false
const timeout = setTimeout(() => ws.terminate(), 30_000)

ws.on('open', () => {
  ws.send(JSON.stringify({
    event: 'start',
    request: {
      partner_session_id: process.env.NARYA_PARTNER_SESSION_ID ?? `session_${randomUUID()}`,
      context_id: 'assistant_turn_1',
      voice_id: voiceId,
      output_format: format,
    },
  }))
  ws.send(JSON.stringify({ event: 'text', text: 'Hello from Narya streaming TTS.' }))
  ws.send(JSON.stringify({ event: 'stop' }))
})

ws.on('message', async (raw) => {
  try {
    const event = JSON.parse(raw.toString())
    if (event.event === 'audio') {
      if (chunks.size && event.format !== format) throw new Error('Audio format changed within the stream')
      chunks.set(event.seq, Buffer.from(event.audio, 'base64'))
      format = event.format
    } else if (event.event === 'error') {
      throw new Error(`${event.code}: ${event.detail}`)
    } else if (event.event === 'finish') {
      const audio = Buffer.concat([...chunks.entries()].sort(([a], [b]) => a - b).map(([, bytes]) => bytes))
      if (event.reason !== 'stop' || !audio.length) throw new Error('TTS finished without complete audio')
      completed = true
      clearTimeout(timeout)
      const suffix = format.startsWith('opus') ? 'opus' : format.startsWith('aac') ? 'aac' : 'pcm'
      await writeFile(`output.${suffix}`, audio)
      console.log('request', event.request_id, 'audit', event.audit_id)
      ws.close()
    }
  } catch (error) {
    clearTimeout(timeout)
    console.error(error)
    process.exitCode = 1
    ws.terminate()
  }
})
ws.on('error', (error) => {
  console.error(error)
  process.exitCode = 1
})
ws.on('close', () => {
  clearTimeout(timeout)
  if (!completed) process.exitCode = 1
})
run
NARYA_TTS_BASE_URL=https://aniwaffle.com \
NARYA_TTS_WS_URL=wss://aniwaffle.com/v1/tts/stream \
NARYA_TTS_API_KEY=awp_... \
NARYA_VOICE_ID=your_narya_voice_id \
npx tsx stream.ts
Integration boundary

Wrap this transport code in your own speech client so request IDs, metrics, playback queues, cancellation, and retry policy have one owner in your application.

Contact our team

Tell us about your character and what you’d like to build.