TTS API reference

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"]
    }
  ]
}

# 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

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

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

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

{
  "event": "start",
  "request": {
    "partner_session_id": "conversation_42",
    "voice_id": "<voice-id-from-get-v1-voices>",
    "output_format": "opus_48000_64",
    "params": {
      "voice_tags": ["panting"]
    }
  }
}

{"event":"text","text":"Your order is ready, "}
{"event":"flush"}
{"event":"text","text":"and it will arrive tomorrow."}
{"event":"stop"}

{
  "event": "audio",
  "request_id": "rq_018f...",
  "context_id": "assistant_turn_7",
  "seq": 1,
  "audio": "AAABAAIA...",
  "format": "pcm_44100"
}

{
  "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"
  }
}

{
  "event": "error",
  "request_id": "rq_018f...",
  "code": "provider_unavailable",
  "retryable": true,
  "detail": "The requested voice is temporarily unavailable."
}

npm install ws
npm install --save-dev tsx typescript @types/ws

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) => {
  const event = JSON.parse(raw.toString())
  if (event.event === 'audio') {
    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 = [...chunks.entries()].sort(([a], [b]) => a - b).map(([, bytes]) => bytes)
    const suffix = format.startsWith('opus') ? 'opus' : format.startsWith('aac') ? 'aac' : 'pcm'
    await writeFile(`output.${suffix}`, Buffer.concat(audio))
    completed = true
    clearTimeout(timeout)
    console.log('request', event.request_id, 'audit', event.audit_id)
    ws.close()
  }
})
ws.on('close', () => {
  clearTimeout(timeout)
  if (!completed) process.exitCode = 1
})

NARYA_TTS_BASE_URL=https://animated-waffle-dev.narya.ai \
NARYA_TTS_WS_URL=wss://animated-waffle-dev.narya.ai/v1/tts/stream \
NARYA_TTS_API_KEY=awp_... \
NARYA_VOICE_ID=your_narya_voice_id \
npx tsx stream.ts