Vakyam TypeScript SDK

Node TypeScript SDK for the Vakyam Text-to-Speech API.

Install

npm install @vakyam-ai/tts

Requires Node.js 20 or newer.

Clients

Use VakyamAI for normal HTTP calls:

import { VakyamAI } from "@vakyam-ai/tts";

const Vakyam = new VakyamAI({
  apiKey: process.env.VAKYAM_API_KEY!,
});

Use VakyamAIAsync for HTTP streaming and WebSocket streaming:

import { VakyamAIAsync } from "@vakyam-ai/tts";

const Vakyam = new VakyamAIAsync({
  apiKey: process.env.VAKYAM_API_KEY!,
});

By default, the SDK connects to the hosted Vakyam API. If you have a custom deployment, pass baseUrl:

const Vakyam = new VakyamAI({
  apiKey: process.env.VAKYAM_API_KEY!,
  baseUrl: "https://your-api.example.com",
});

List Voices

const voicesByLanguage = await Vakyam.voices.list();
const voicesByName = await Vakyam.voices.list({ groupBy: "voice" });

Use the returned voice_name as voice with its language code in TTS requests. Custom voices use a public ID beginning with vc_.

Generate Text To Speech

import { writeFile } from "node:fs/promises";

const result = await Vakyam.tts.generate({
  text: "வணக்கம்",
  model_id: "raaga-v1",
  voice: "Archana",
  language: "ta-IN",
  output_format: "mp3",
  sample_rate: 24000,
});

await writeFile(`speech.${result.format}`, result.audioBytes);

result.audio is the original base64 API response. result.audioBytes is decoded audio as Uint8Array.

HTTP Streaming

import { createWriteStream } from "node:fs";
import { VakyamAIAsync } from "@vakyam-ai/tts";

const Vakyam = new VakyamAIAsync({
  apiKey: process.env.VAKYAM_API_KEY!,
});

const output = createWriteStream("speech.pcm");

for await (const chunk of Vakyam.tts.stream({
  text: "Hello",
  model_id: "raaga-v1",
  voice: "Archana",
  language: "en-IN",
  output_format: "pcm",
  sample_rate: 24000,
})) {
  output.write(chunk);
}

output.end();

WebSocket Streaming

import { writeFile } from "node:fs/promises";
import { VakyamAIAsync } from "@vakyam-ai/tts";

const Vakyam = new VakyamAIAsync({
  apiKey: process.env.VAKYAM_API_KEY!,
});

const socket = await Vakyam.tts.websocket({
  model_id: "raaga-v1",
  voice: "Archana",
  language: "en-IN",
  output_format: "pcm",
  sample_rate: 24000,
});

const utterance = await socket.sendText("Hello.");
await writeFile("speech.pcm", utterance.audioBytes);

socket.close();

Send one complete sentence or utterance per sendText() call.

To interrupt a currently streaming utterance, call cancel(). It resolves after the API sends its cancellation terminal message and includes any audio chunks that arrived before cancellation. The socket remains usable for the next turn.

const turn = socket.sendText("A longer sentence that may be interrupted.");
const cancelled = await socket.cancel();
console.log(cancelled.characters_used, cancelled.audioBytes);
await turn; // resolves with the same cancellation result

Errors

import {
  VakyamAPIError,
  VakyamValidationError,
  VakyamWebSocketError,
} from "@vakyam-ai/tts";

try {
  await Vakyam.tts.generate({
    text: "Hello",
    model_id: "raaga-v1",
    voice: "Archana",
    language: "en-IN",
    sample_rate: 24000,
  });
} catch (error) {
  if (error instanceof VakyamValidationError) {
    console.error(error.field, error.message);
  } else if (error instanceof VakyamAPIError) {
    console.error(error.statusCode, error.code, error.message);
  } else if (error instanceof VakyamWebSocketError) {
    console.error(error.code, error.message);
  } else {
    throw error;
  }
}

Supported Methods

await Vakyam.voices.list();
await Vakyam.voices.list({ groupBy: "voice" });
await Vakyam.tts.generate({...});

for await (const chunk of Vakyam.tts.stream({...})) {}
const socket = await Vakyam.tts.websocket({...});