Text to Speech
TTS API reference
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.
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
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.
| Environment | HTTP base URL | WebSocket endpoint |
|---|---|---|
| Production · US | https://aniwaffle.com | wss://aniwaffle.com/v1/tts/stream |
| Production · Japan | https://jp.aniwaffle.com | wss://jp.aniwaffle.com/v1/tts/stream |
| Development · US | https://dev.aniwaffle.com | wss://dev.aniwaffle.com/v1/tts/stream |
| Development · Japan | https://dev.jp.aniwaffle.com | wss://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.
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_idFor 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.
NARYA_TTS_BASE_URL=https://jp.aniwaffle.com
NARYA_TTS_WS_URL=wss://jp.aniwaffle.com/v1/tts/streamVoice 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.
curl --request GET \
--url "$NARYA_TTS_BASE_URL/v1/voices" \
--header "Authorization: Bearer $NARYA_TTS_API_KEY"{
"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
}
]
}| Field | Type | Required | Description |
|---|---|---|---|
| voices[].id | string | Yes | Pass this Narya-owned value as voice_id to one-shot or streaming TTS. |
| voices[].name | string | Yes | Human-readable display name. Includes the model name when a voice has multiple routes; use the corresponding id to select that model. |
| voices[].output_formats | string[] | Yes | Formats this voice can deliver without provider-specific substitution. |
| voices[].capabilities | string[] | Yes | Features supported by this exact voice variant. Check for voice_tags before sending expressive cues. |
| voices[].nsfw | boolean | Yes | True when the voice is intended for adult content. Public-facing applications should filter these voices out unless the surface is explicitly age-gated. |
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.
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.
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.
Discover
Choose an exact voice id from GET /v1/voices.
Send
Derive its format, then POST the TTS request.
Save
Write the response body as audio bytes.
# 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.audioimport { 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'))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.
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.
python -m pip install "pipecat-ai==1.4.0" "websockets>=15,<17"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()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,
),
)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.
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.
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
- 1Open the production Dashboard and sign in. Creating keys requires a workspace Owner, Admin, or Builder role.
- 2Select Integrations in the sidebar (under the Config group). The page is titled API keys.
- 3Enter a descriptive Label such as checkout-voice-prod and select Create key.
- 4Copy the full awp_ value from the "Key created. Copy it now, it won't be shown again." banner. Only its hash is retained.
- 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
startis sent after revocation; revocation does not close that connection.
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.
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'))| Field | Type | Required | Description |
|---|---|---|---|
| text | string | Yes | Complete UTF-8 text, 1 to 20,000 characters. Emotion tags go inline; see Emotion tags. |
| voice_id | string | Yes | Narya voice ID returned by GET /v1/voices. |
| output_format | enum | Yes | A format listed for this voice. |
| realtime | boolean | No | Defaults 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. |
| channels | 1 or 2 | No | Defaults to 1. Stereo requires 2, a voice with the stereo capability, and PCM output. |
| partner_session_id | string | No | Optional external correlation ID. Omit it when you do not have one. |
| context_id | string | No | Your turn or playback-context ID. |
| params.speed | positive number | No | Speaking-speed multiplier when supported by the selected voice. |
response bodyHTTP 200Raw audio bytes. Use Content-Type and X-Audio-Format to select the decoder or filename.
response headersHTTP 200X-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.
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.
{
"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.
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.
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.
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.
{
"text": "<happy>I am happy to see you today.</happy> [laughing]",
"voice_id": "<voice-id-from-get-v1-voices>",
"output_format": "pcm_24000"
}{
"text": "[panting] [gasping]",
"voice_id": "<voice-id-from-get-v1-voices>",
"output_format": "pcm_24000"
}Send tags inside text events. Keep each paired span balanced before the next flush or stop.
{
"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.
Emotions
happysadangryafraiddisgustedsurprisedembarrassedarousedDelivery
whisperingshoutingHuman sounds
sighinggaspingpantingsniffinglaughinggroaningcryingcoughinglickinginvalid_request. Escape literal \\, [ or < with a backslash.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.
- 1Client
connectOpen 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. - 2Client
startDeclare attribution, the Narya voice ID, and output format exactly once. Narya assigns the request ID and returns it on server events. - 3Client
textSend one or more non-empty text segments unless this is a tag-only request. Segments are appended in wire order. - 4Client
flushOptional. Synthesize the current buffer now and keep the request open for more text. - 5Server
audioReceive zero or more ordered chunks. The first sequence number is 1. - 6Client
stopSynthesize any remaining text, or a tag-only request, and finalize the request. - 7Server
usage → finishRead the terminal metadata, then allow the server to close normally. An error replaces finish when the request fails.
start → (text+ → (flush → text+)*)? → stop
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.
{"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
textevent may contain at most 5,000 characters. - The production request limit is 20,000 characters across all text events.
- An empty buffer on
flushis a no-op. stopflushes 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.
{
"event": "audio",
"request_id": "rq_018f...",
"context_id": "assistant_turn_7",
"seq": 1,
"audio": "AAABAAIA...",
"format": "pcm_44100"
}| Requested format | Nominal encoding | Typical use |
|---|---|---|
| pcm_16000 | Raw 16-bit PCM · 16 kHz | Explicitly 16 kHz-constrained pipelines |
| pcm_24000 | Raw 16-bit PCM · 24 kHz | Voice-agent pipelines standardized on 24 kHz |
| pcm_44100 | Raw 16-bit PCM · 44.1 kHz | Raw PCM compatibility and decoder-free pipelines |
| pcm_48000 | Raw 16-bit PCM · 48 kHz | Native-rate Waffle audio and decoder-free realtime pipelines |
| aac_44100_128 | AAC · 44.1 kHz · 128 kbps | Mobile and media pipelines |
| opus_48000_64 | Ogg Opus · 48 kHz · 64 kbps | Recommended default for modern realtime transport |
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
seqto 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_64is 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_48000plays at 48,000 Hz,pcm_44100at 44,100 Hz, andpcm_24000at 24,000 Hz. PCM16 describes bit depth, not a 16 kHz rate. Waffle streams at these three rates and rejectspcm_16000. - Stereo PCM interleaves complete sample frames:
L0, R0, L1, R1, .... Each stereo frame is four bytes. Duration in seconds isbyteLength / (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
pcmas 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.
{"event":"start","request":{"voice_id":"<stereo-voice-id>","output_format":"pcm_48000","channels":2}}{"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.
{
"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"
}
}| Field | Type | Required | Description |
|---|---|---|---|
| event | "start" | Yes | Discriminator for the first control event. |
| request.partner_session_id | string | No | Optional external audit correlation ID, 1–200 characters. It never owns billing or idempotency. |
| request.context_id | string | No | Your turn, message, or playback-context ID. Echoed on audio events when supplied. |
| request.voice_id | string | Yes | Narya voice identifier returned by GET /v1/voices. |
| request.output_format | enum | Yes | Requested audio format. See Handle audio output. |
| request.realtime | boolean | No | Defaults 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.channels | 1 or 2 | No | Defaults to 1. Use 2 with a stereo-capable voice and PCM output. |
| request.params.speed | positive number | No | Optional speaking-speed multiplier when supported by the selected voice. |
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 moreAdds a non-empty text string to the current buffer. Maximum 5,000 characters per event.
flushoptionalSynthesizes the current buffer and keeps the request open. Has no additional fields.
stopexactly onceSynthesizes remaining text, emits terminal metadata, and ends the request.
| Field | Type | Required | Description |
|---|---|---|---|
| text.event | "text" | Yes | Text-event discriminator. |
| text.text | string | Yes | Non-empty UTF-8 text, at most 5,000 characters. |
| flush.event | "flush" | Yes | Flush-event discriminator. No other fields. |
| stop.event | "stop" | Yes | Stop-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 moreBase64 audio bytes plus request ID, optional context ID, one-based sequence number, and delivered format.
usageonce on successCharacter and generated-audio totals plus the Narya voice ID.
finishterminal successFinal 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 failureStable code, optional detail, and the retryability decision for this failure.
{
"event": "usage",
"request_id": "rq_018f...",
"usage": { "chars": 48, "audio_ms": 2760 },
"voice_id": "<voice-id-returned-by-GET-/v1/voices>"
}{
"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
}{
"event": "error",
"request_id": "rq_018f...",
"code": "provider_unavailable",
"retryable": true,
"detail": "The requested voice is temporarily unavailable."
}| Field | Type | Required | Description |
|---|---|---|---|
| audio.seq | integer | Audio | One-based chunk sequence across the complete request, including multiple flushes. |
| audio.audio | base64 string | Audio | Encoded bytes for this chunk. |
| audio.format | string | Audio | Delivered wire format. Use this value to choose the decoder. |
| usage.usage.chars | integer | Usage | Characters synthesized successfully across all segments. |
| usage.usage.audio_ms | integer | Usage | Generated media duration in milliseconds. Supplier billable usage is retained in the model call audit; historical requests keep their frozen tariff. |
| finish.audit_id | string | Finish | Audit correlation ID to include in support requests. |
| finish.audio_persisted | boolean | Finish | True 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.retryable | boolean | Error | Authoritative 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.
| Code | Retry? | Client action |
|---|---|---|
| unauthorized | No | Correct, rotate, or re-scope the credential before reconnecting. |
| invalid_request | No | Fix JSON, event order, configuration, or input limits. |
| invalid_voice | No | The 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_format | No | The selected voice cannot produce this format (HTTP 400 on one-shot). Choose a format returned for that voice by GET /v1/voices. |
| provider_auth_missing | No | Contact Narya or use an approved configured fallback. |
| provider_unavailable | If retryable=true | Open a new connection after exponential backoff with jitter. |
| provider_error | If retryable=true | Retry only when explicitly allowed; otherwise escalate with the audit ID. |
| rate_limited | Yes, after backoff | Request 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_credit | No | The workspace has insufficient credits (HTTP 402 on one-shot). Contact Narya to arrange additional credits before retrying. |
| organization_suspended | No | The workspace is suspended (HTTP 403). Contact Narya. |
| capability_disabled | No | TTS is not enabled for this workspace (HTTP 403). Contact Narya. |
| organization_account_missing | No | Workspace 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.
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
v1.10.0
v1.9.0
- Deprecated
params.voice_tagson one-shot and streaming requests. It is still accepted but ignored; put tags inline intextinstead. - One-shot
textmust now contain at least one character. For a sound-only request, send the tag as text, such as[laughing].
v1.6.0
v1.5.0
- 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
- 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
- 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
- Made request_id server-owned for every one-shot and streaming request.
v1.1.0
- Added POST /v1/tts and GET /v1/voices with provider-neutral voice IDs.
v1.0.0
- 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.
npm install ws
npm install --save-dev tsx typescript @types/wsimport { 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
})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.tsWrap this transport code in your own speech client so request IDs, metrics, playback queues, cancellation, and retry policy have one owner in your application.