voicekit-client 0.1.0

package/README.md

@@ -0,0 +1,128 @@
+# VoiceKit — TypeScript SDK
+
+Official TypeScript/JavaScript wrapper for [VoiceKit](https://ttsapi.ru):
+neural speech synthesis, transcription, sentiment analysis, and batch operations.
+
+Zero runtime dependencies. Requires Node.js 18+ (global `fetch`).
+
+## Install
+
+```bash
+npm install voicekit-client
+```
+
+## Quick start
+
+```js
+import { VoiceKitClient, b64 } from "voicekit-client";
+import { writeFile } from "node:fs/promises";
+
+const client = new VoiceKitClient({ apiKey: "YOUR_KEY" });
+
+// Synthesis → raw audio bytes
+const audio = await client.synthesize("Привет! Это синтез русской речи.", {
+  voice: "preset_anna",
+  format: "mp3",
+});
+await writeFile("speech.mp3", audio);
+
+// Streaming (Pro/Business)
+for await (const chunk of client.synthesizeStream("Первое предложение. Второе.")) {
+  // write chunks to a file or socket
+}
+
+// Transcription (async → poll)
+const job = await client.transcribe("audio.wav", { keyterms: ["диагноз"] });
+let result = await client.getTranscriptionJob(job.job_id);
+while (!["completed", "failed"].includes(result.status)) {
+  await new Promise(r => setTimeout(r, 1000));
+  result = await client.getTranscriptionJob(job.job_id);
+}
+
+// Short-file sync transcription
+const transcript = await client.transcribeSync("audio.wav");
+
+// Analysis (sentiment + keywords + entities)
+const analysis = await client.analyzeSync("audio.wav");
+
+// Text intelligence
+const moderation = await client.moderate("Это оскорбительное сообщение.");
+
+// Batches
+const batch = await client.batchSynthesize([
+  { text: "Первый текст", voice: "preset_anna" },
+  { text: "Второй текст", voice: "dmitri" },
+]);
+const status = await client.getBatch(batch.batch_id);
+
+const analysisBatch = await client.batchAnalyze([
+  { audio: await b64("a.wav"), language: "ru" },
+  { audio: await b64("b.wav"), language: "ru" },
+]);
+
+// Voice cloning (Pro/Business)
+const clone = await client.createCloneVoice({
+  name: "My voice",
+  promptText: "Точный текст образца.",
+  samples: "reference.wav",
+});
+console.log(await client.listCloneVoices());
+await client.deleteCloneVoice(clone.id);
+
+// VAD (speech segments)
+const segments = await client.vad("audio.wav");
+
+// Account
+const usage = await client.usage();
+const balance = await client.billingBalance();
+```
+
+### Audio effects (Pro/Business)
+
+```js
+// Inline during synthesis — the chain is applied to the synthesized audio
+const fxAudio = await client.synthesize("Привет!", {
+  effects: '[{"type":"reverb","room_size":0.5},{"type":"pitch","semitones":2}]',
+});
+
+// Async processing of an existing file
+const fxJob = await client.applyAudioEffects("voice.mp3", [{ type: "compressor", ratio: 3 }]);
+let fxResult = await client.getAudioEffectsJob(fxJob.job_id);
+while (!["completed", "failed"].includes(fxResult.status)) {
+  await new Promise(r => setTimeout(r, 1000));
+  fxResult = await client.getAudioEffectsJob(fxJob.job_id);
+}
+const fxFile = await client.downloadAudioEffects(fxJob.job_id);
+await writeFile("voice_fx.mp3", fxFile);
+```
+
+### WebSocket streaming (Pro/Business)
+
+```js
+const stream = await client.transcribeStream({ language: "ru", keyterms: ["диагноз"] });
+await stream.sendAudio(pcm16Chunk1); // raw PCM16, 16 kHz mono (Uint8Array)
+await stream.sendAudio(pcm16Chunk2);
+await stream.stop();                 // finalize the utterance
+for await (const event of stream.events()) {
+  console.log(event.type, event);    // session / vad / partial / final / error
+}
+stream.close();
+
+const vad = await client.vadStream(); // VAD events only (speech_started/ended)
+await vad.sendAudio(pcm16Chunk);
+await vad.stop();
+for await (const event of vad.events()) {
+  console.log(event.type, event);
+}
+vad.close();
+```
+
+## Configuration
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `apiKey` | — | API key (required) |
+| `baseUrl` | `https://ttsapi.ru` | API base URL (e.g. `http://localhost:5080` for local dev) |
+| `timeoutMs` | `120000` | Per-request timeout in milliseconds |
+
+Errors reject with `VoiceKitError` (`.status`, `.code`, `.message`).

package/index.d.ts

@@ -0,0 +1,150 @@
+export type AudioSource = Uint8Array | string;
+
+export interface VoiceKitClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+}
+
+export class VoiceKitError extends Error {
+  readonly status: number;
+  readonly code: string;
+}
+
+export class VoiceKitClient {
+  constructor(options: VoiceKitClientOptions);
+
+  synthesize(text: string, opts?: SynthesisOptions): Promise<Uint8Array>;
+  synthesizeStream(text: string, opts?: SynthesisOptions): AsyncGenerator<Uint8Array>;
+  synthesizeAsync(
+    text: string,
+    opts?: SynthesisAsyncOptions,
+  ): Promise<Record<string, unknown>>;
+  getSynthesisJob(jobId: string): Promise<Record<string, unknown>>;
+  downloadSynthesisAudio(jobId: string): Promise<Uint8Array>;
+  voices(): Promise<Array<Record<string, unknown>>>;
+  voice(id: string): Promise<Record<string, unknown>>;
+
+  createCloneVoice(input: CloneVoiceCreateInput): Promise<Record<string, unknown>>;
+  listCloneVoices(): Promise<Array<Record<string, unknown>>>;
+  getCloneVoice(cloneId: string): Promise<Record<string, unknown>>;
+  deleteCloneVoice(cloneId: string): Promise<void>;
+
+  transcribe(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
+  transcribeSync(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
+  getTranscriptionJob(jobId: string): Promise<Record<string, unknown>>;
+  subtitles(jobId: string, format?: "vtt" | "srt"): Promise<string>;
+  vad(audio: AudioSource): Promise<Record<string, unknown>>;
+
+  analyze(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
+  analyzeSync(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
+  getAnalysisJob(jobId: string): Promise<Record<string, unknown>>;
+
+  detectLanguage(text: string): Promise<Record<string, unknown>>;
+  redact(text: string, language?: string): Promise<Record<string, unknown>>;
+  topics(text: string, language?: string): Promise<Record<string, unknown>>;
+  summarize(
+    text: string,
+    language?: string,
+    maxSentences?: number,
+  ): Promise<Record<string, unknown>>;
+
+  moderate(text: string, language?: string): Promise<Record<string, unknown>>;
+
+  applyAudioEffects(
+    audio: AudioSource,
+    effects: Array<Record<string, unknown>>,
+    opts?: AudioEffectsOptions,
+  ): Promise<Record<string, unknown>>;
+  getAudioEffectsJob(jobId: string): Promise<Record<string, unknown>>;
+  downloadAudioEffects(jobId: string): Promise<Uint8Array>;
+
+  applyVideoEffects(
+    video: AudioSource,
+    effects: Array<Record<string, unknown>>,
+    opts?: VideoEffectsOptions,
+  ): Promise<Record<string, unknown>>;
+  getVideoEffectsJob(jobId: string): Promise<Record<string, unknown>>;
+  downloadVideoEffects(jobId: string): Promise<Uint8Array>;
+
+  batchSynthesize(items: Array<Record<string, unknown>>): Promise<Record<string, unknown>>;
+  batchAnalyze(items: Array<Record<string, unknown>>): Promise<Record<string, unknown>>;
+  getBatch(batchId: string): Promise<Record<string, unknown>>;
+
+  usage(): Promise<Record<string, unknown>>;
+  billingBalance(): Promise<Record<string, unknown>>;
+
+  transcribeStream(opts?: TranscribeStreamOptions): Promise<WsStream>;
+  vadStream(): Promise<WsStream>;
+}
+
+export interface SynthesisOptions {
+  voice?: string;
+  format?: "mp3" | "wav" | "ogg";
+  sampleRate?: number;
+  speed?: number;
+  pitch?: number;
+  emotion?: string;
+  ssml?: boolean;
+  putAccent?: boolean;
+  putYo?: boolean;
+  normalize?: boolean;
+  model?: string;
+  language?: string;
+  effects?: string;
+}
+
+export interface AudioEffectsOptions {
+  outputFormat?: "wav" | "mp3" | "ogg";
+  webhookUrl?: string;
+}
+
+export interface VideoEffectsOptions {
+  mode?: "mux" | "audio";
+  audio?: AudioSource;
+  outputFormat?: string;
+  webhookUrl?: string;
+}
+
+export interface SynthesisAsyncOptions {
+  voice?: string;
+  format?: "wav";
+  sampleRate?: number;
+  speed?: number;
+  model?: string;
+  language?: string;
+  webhookUrl?: string;
+}
+
+export interface AudioOptions {
+  language?: string;
+  diarization?: boolean;
+  webhookUrl?: string;
+  keyterms?: string[];
+  emotions?: boolean;
+  keywords?: boolean;
+  entities?: boolean;
+}
+
+export interface CloneVoiceCreateInput {
+  name: string;
+  promptText: string;
+  samples: AudioSource | AudioSource[];
+  language?: string;
+}
+
+export interface TranscribeStreamOptions {
+  language?: string;
+  keyterms?: string[];
+  interim?: boolean;
+}
+
+export class WsStream {
+  sendAudio(pcm16: Uint8Array): Promise<void>;
+  sendText(payload: unknown): Promise<void>;
+  stop(): Promise<void>;
+  events(): AsyncGenerator<Record<string, unknown>>;
+  close(): void;
+}
+
+export function b64(audio: AudioSource): Promise<string>;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "voicekit-client",
+  "version": "0.1.0",
+  "description": "Official TypeScript/JavaScript SDK for VoiceKit (synthesis, transcription, analysis, moderation, batches).",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "keywords": [
+    "tts",
+    "speech",
+    "synthesis",
+    "transcription",
+    "stt",
+    "voice",
+    "russian"
+  ],
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://ttsapi.ru"
+  }
+}

package/src/index.js

@@ -0,0 +1,645 @@
+/**
+ * Official JavaScript/TypeScript SDK for VoiceKit.
+ *
+ * Requires Node.js 18+ (global `fetch`, web streams). Zero runtime dependencies.
+ *
+ * @example
+ * import { VoiceKitClient } from "voicekit-client";
+ *
+ * const client = new VoiceKitClient({ apiKey: "YOUR_KEY" });
+ * const audio = await client.synthesize("Привет!", { voice: "preset_anna", format: "mp3" });
+ * await import("node:fs/promises").then(fs => fs.writeFile("speech.mp3", audio));
+ */
+
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const DEFAULT_BASE_URL = "https://ttsapi.ru";
+
+export class VoiceKitError extends Error {
+  /**
+   * @param {number} status HTTP status code.
+   * @param {string} message Human-readable message.
+   * @param {string} [code] Machine-readable error code.
+   */
+  constructor(status, message, code = "") {
+    super(message);
+    this.name = "VoiceKitError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+/**
+ * Audio input: raw bytes or a path to a local file.
+ * @typedef {Uint8Array | string} AudioSource
+ */
+
+/**
+ * Client options.
+ * @typedef {object} VoiceKitClientOptions
+ * @property {string} apiKey API key (required).
+ * @property {string} [baseUrl] API base URL. Defaults to `https://ttsapi.ru`.
+ * @property {number} [timeoutMs] Per-request timeout in milliseconds. Defaults to 120000.
+ */
+
+export class VoiceKitClient {
+  /**
+   * @param {VoiceKitClientOptions} options
+   */
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, timeoutMs = 120_000 }) {
+    if (!apiKey) throw new Error("apiKey is required");
+    /** @private */ this._baseUrl = baseUrl.replace(/\/+$/, "");
+    /** @private */ this._headers = { "X-Api-Key": apiKey };
+    /** @private */ this._timeoutMs = timeoutMs;
+  }
+
+  // ──────────────────────── Synthesis ────────────────────────────────
+
+  /**
+   * Synthesize speech and return raw audio bytes.
+   * @param {string} text
+   * @param {object} [opts]
+   * @returns {Promise<Uint8Array>}
+   */
+  async synthesize(text, opts = {}) {
+    const body = compact({ text, ...opts });
+    const response = await this.#request("/v1/synthesize", { method: "POST", json: body });
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  /**
+   * Synthesize and yield audio chunks as they are produced (Pro/Business).
+   * @param {string} text
+   * @param {object} [opts]
+   * @returns {AsyncGenerator<Uint8Array>}
+   */
+  async *synthesizeStream(text, opts = {}) {
+    const body = compact({ text, ...opts });
+    const response = await this.#request("/v1/synthesize/stream", { method: "POST", json: body });
+    const reader = response.body?.getReader();
+    if (!reader) return;
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value?.length) yield value;
+    }
+  }
+
+  /**
+   * Queue a long-form (audiobook) synthesis job; poll with `getSynthesisJob()`.
+   * Long-form synthesis returns WAV only.
+   * @param {string} text
+   * @param {object} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async synthesizeAsync(text, opts = {}) {
+    const { webhookUrl, ...body } = opts;
+    const query = webhookUrl ? `?webhookUrl=${encodeURIComponent(webhookUrl)}` : "";
+    const response = await this.#request(`/v1/synthesize/async${query}`, {
+      method: "POST",
+      json: compact({ text, ...body }),
+    });
+    return response.json();
+  }
+
+  /**
+   * Poll a long-form synthesis job; returns the audiobook manifest when done.
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getSynthesisJob(jobId) {
+    return this.#getJson(`/v1/synthesize/async/${jobId}`);
+  }
+
+  /**
+   * Download the produced WAV for a completed long-form synthesis job.
+   * @param {string} jobId
+   * @returns {Promise<Uint8Array>}
+   */
+  async downloadSynthesisAudio(jobId) {
+    const response = await this.#request(`/v1/synthesize/async/${jobId}/audio`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  /** @returns {Promise<Array<Record<string, unknown>>>} */
+  voices() {
+    return this.#getJson("/v1/voices");
+  }
+
+  /**
+   * @param {string} id Voice id, e.g. `preset_anna`.
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  voice(id) {
+    return this.#getJson(`/v1/voices/${id}`);
+  }
+
+  // ──────────────────────── Voice cloning ────────────────────────────
+
+  /**
+   * Create a cloned voice from reference audio (Pro/Business).
+   * @param {{ name: string, promptText: string, samples: AudioSource | AudioSource[], language?: string }} input
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async createCloneVoice({ name, promptText, samples, language }) {
+    const sampleList = Array.isArray(samples) ? samples : [samples];
+    const form = new FormData();
+    form.append("name", name);
+    form.append("prompt_text", promptText);
+    if (language) form.append("language", language);
+    for (const sample of sampleList) {
+      const { data, filename } = await audioToParts(sample);
+      form.append("samples", new Blob([data], { type: "audio/wav" }), filename);
+    }
+    const response = await this.#request("/v1/voices/clone", { method: "POST", form });
+    return response.json();
+  }
+
+  /** @returns {Promise<Array<Record<string, unknown>>>} */
+  listCloneVoices() {
+    return this.#getJson("/v1/voices/clone");
+  }
+
+  /**
+   * @param {string} cloneId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getCloneVoice(cloneId) {
+    return this.#getJson(`/v1/voices/clone/${cloneId}`);
+  }
+
+  /**
+   * @param {string} cloneId
+   * @returns {Promise<void>}
+   */
+  async deleteCloneVoice(cloneId) {
+    await this.#request(`/v1/voices/clone/${cloneId}`, { method: "DELETE" });
+  }
+
+  // ──────────────────────── Transcription ────────────────────────────
+
+  /**
+   * Start an async transcription job; poll with `getTranscriptionJob()`.
+   * @param {AudioSource} audio
+   * @param {object} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async transcribe(audio, opts = {}) {
+    return this.#postForm("/v1/transcribe", audio, opts);
+  }
+
+  /**
+   * Transcribe a short file (≤ 3 min) synchronously.
+   * @param {AudioSource} audio
+   * @param {object} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async transcribeSync(audio, opts = {}) {
+    return this.#postForm("/v1/transcribe/sync", audio, opts);
+  }
+
+  /**
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getTranscriptionJob(jobId) {
+    return this.#getJson(`/v1/transcribe/${jobId}`);
+  }
+
+  /**
+   * Download VTT/SRT subtitles for a completed transcription job.
+   * @param {string} jobId
+   * @param {"vtt" | "srt"} [format]
+   * @returns {Promise<string>}
+   */
+  async subtitles(jobId, format = "vtt") {
+    const response = await this.#request(`/v1/transcribe/${jobId}/subtitles?format=${format}`);
+    return response.text();
+  }
+
+  /**
+   * Detect speech segments in an audio file (Silero VAD).
+   * @param {AudioSource} audio
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  vad(audio) {
+    return this.#postForm("/v1/vad", audio, {});
+  }
+
+  // ──────────────────────── Analysis ─────────────────────────────────
+
+  /**
+   * Start an async analysis job; poll with `getAnalysisJob()`.
+   * @param {AudioSource} audio
+   * @param {object} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async analyze(audio, opts = {}) {
+    return this.#postForm("/v1/analyze", audio, opts);
+  }
+
+  /**
+   * Analyze a short file (≤ 3 min) synchronously.
+   * @param {AudioSource} audio
+   * @param {object} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async analyzeSync(audio, opts = {}) {
+    return this.#postForm("/v1/analyze/sync", audio, opts);
+  }
+
+  /**
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getAnalysisJob(jobId) {
+    return this.#getJson(`/v1/analyze/${jobId}`);
+  }
+
+  // ──────────────────────── Text intelligence ────────────────────────
+
+  /** @param {string} text */
+  detectLanguage(text) {
+    return this.#postJson("/v1/detect-language", { text });
+  }
+
+  /** @param {string} text */
+  redact(text, language) {
+    return this.#postJson("/v1/redact", compact({ text, language }));
+  }
+
+  /** @param {string} text */
+  topics(text, language) {
+    return this.#postJson("/v1/analyze/topics", compact({ text, language }));
+  }
+
+  /** @param {string} text */
+  summarize(text, language, maxSentences) {
+    return this.#postJson(
+      "/v1/analyze/summarize",
+      compact({ text, language, max_sentences: maxSentences }),
+    );
+  }
+
+  /**
+   * Flag profanity, insults and hate speech in raw text.
+   * @param {string} text
+   * @param {string} [language]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  moderate(text, language) {
+    return this.#postJson("/v1/moderate", compact({ text, language }));
+  }
+
+  // ──────────────────────── Audio / video effects ───────────────────
+
+  /**
+   * Start an async audio-effects job; poll with `getAudioEffectsJob()`.
+   * @param {AudioSource} audio
+   * @param {Array<Record<string, unknown>>} effects Effect descriptors.
+   * @param {{ outputFormat?: string, webhookUrl?: string }} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async applyAudioEffects(audio, effects, opts = {}) {
+    const { outputFormat = "wav", webhookUrl } = opts;
+    const { data, filename } = await audioToParts(audio);
+    const form = new FormData();
+    form.append("audio", new Blob([data], { type: "audio/wav" }), filename);
+    form.append("effects", JSON.stringify(effects));
+    form.append("output_format", outputFormat);
+    const query = webhookUrl ? `?webhookUrl=${encodeURIComponent(webhookUrl)}` : "";
+    const response = await this.#request(`/v1/audio/effects${query}`, { method: "POST", form });
+    return response.json();
+  }
+
+  /**
+   * Poll an audio-effects job; returns the manifest when completed.
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getAudioEffectsJob(jobId) {
+    return this.#getJson(`/v1/audio/effects/${jobId}`);
+  }
+
+  /**
+   * Download the produced audio for a completed audio-effects job.
+   * @param {string} jobId
+   * @returns {Promise<Uint8Array>}
+   */
+  async downloadAudioEffects(jobId) {
+    const response = await this.#request(`/v1/audio/effects/${jobId}/audio`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  /**
+   * Start an async video-effects job; poll with `getVideoEffectsJob()`.
+   * @param {AudioSource} video
+   * @param {Array<Record<string, unknown>>} effects Effect descriptors.
+   * @param {{ mode?: string, audio?: AudioSource, outputFormat?: string, webhookUrl?: string }} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async applyVideoEffects(video, effects, opts = {}) {
+    const { mode = "mux", audio, outputFormat, webhookUrl } = opts;
+    const { data, filename } = await audioToParts(video);
+    const form = new FormData();
+    form.append("video", new Blob([data], { type: "video/mp4" }), filename);
+    if (audio) {
+      const parts = await audioToParts(audio);
+      form.append("audio", new Blob([parts.data], { type: "audio/wav" }), parts.filename);
+    }
+    form.append("effects", JSON.stringify(effects));
+    form.append("mode", mode);
+    if (outputFormat) form.append("output_format", outputFormat);
+    const query = webhookUrl ? `?webhookUrl=${encodeURIComponent(webhookUrl)}` : "";
+    const response = await this.#request(`/v1/video/effects${query}`, { method: "POST", form });
+    return response.json();
+  }
+
+  /**
+   * Poll a video-effects job; returns the manifest when completed.
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getVideoEffectsJob(jobId) {
+    return this.#getJson(`/v1/video/effects/${jobId}`);
+  }
+
+  /**
+   * Download the produced artifact (video or audio) for a video-effects job.
+   * @param {string} jobId
+   * @returns {Promise<Uint8Array>}
+   */
+  async downloadVideoEffects(jobId) {
+    const response = await this.#request(`/v1/video/effects/${jobId}/file`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  // ──────────────────────── Batch ────────────────────────────────────
+
+  /**
+   * Queue a batch of synthesis requests; poll with `getBatch()`.
+   * @param {Array<Record<string, unknown>>} items
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  batchSynthesize(items) {
+    return this.#postJson("/v1/batch/synthesize", { items });
+  }
+
+  /**
+   * Queue a batch of analysis requests; each item needs inline base64 `audio`.
+   * @param {Array<Record<string, unknown>>} items
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  batchAnalyze(items) {
+    return this.#postJson("/v1/batch/analyze", { items });
+  }
+
+  /**
+   * @param {string} batchId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getBatch(batchId) {
+    return this.#getJson(`/v1/batch/${batchId}`);
+  }
+
+  // ──────────────────────── Account ──────────────────────────────────
+
+  /** @returns {Promise<Record<string, unknown>>} */
+  usage() {
+    return this.#getJson("/v1/usage");
+  }
+
+  /** @returns {Promise<Record<string, unknown>>} */
+  billingBalance() {
+    return this.#getJson("/v1/billing/balance");
+  }
+
+  // ──────────────────────── Streaming (WebSocket) ────────────────────
+
+  /**
+   * Open a streaming transcription session (Pro/Business).
+   * @param {{ language?: string, keyterms?: string[], interim?: boolean }} [opts]
+   * @returns {Promise<WsStream>}
+   */
+  async transcribeStream({ language, keyterms, interim = true } = {}) {
+    const url = this.#wsUrl("/v1/transcribe/stream", {
+      language,
+      keyterms: Array.isArray(keyterms) ? keyterms.join(",") : undefined,
+      interim,
+    });
+    return openWsStream(url, this._headers);
+  }
+
+  /**
+   * Open a streaming turn-detection session (VAD events only).
+   * @returns {Promise<WsStream>}
+   */
+  async vadStream() {
+    const url = this.#wsUrl("/v1/vad/stream", {});
+    return openWsStream(url, this._headers);
+  }
+
+  // ──────────────────────── Transport ────────────────────────────────
+
+  /**
+   * @param {string} path
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async #getJson(path) {
+    const response = await this.#request(path);
+    return response.json();
+  }
+
+  /**
+   * @param {string} path
+   * @param {Record<string, unknown>} body
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async #postJson(path, body) {
+    const response = await this.#request(path, { method: "POST", json: body });
+    return response.json();
+  }
+
+  /**
+   * @param {string} path
+   * @param {AudioSource} audio
+   * @param {object} opts
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async #postForm(path, audio, opts) {
+    const { data, filename } = await audioToParts(audio);
+    const form = new FormData();
+    form.append("audio", new Blob([data], { type: "audio/wav" }), filename);
+
+    const { keyterms, ...rest } = opts;
+    for (const [key, value] of Object.entries(compact(rest))) {
+      form.append(key, String(value));
+    }
+    if (Array.isArray(keyterms) && keyterms.length) {
+      form.append("keyterms", keyterms.join(","));
+    }
+
+    const response = await this.#request(path, { method: "POST", form });
+    return response.json();
+  }
+
+  /**
+   * @param {string} path
+   * @param {{ method?: string, json?: unknown, form?: FormData }} [options]
+   * @returns {Promise<Response>}
+   */
+  async #request(path, { method = "GET", json, form } = {}) {
+    const headers = { ...this._headers };
+    const init = { method, headers, signal: AbortSignal.timeout(this._timeoutMs) };
+
+    if (json !== undefined) {
+      init.headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(json);
+    } else if (form !== undefined) {
+      init.body = form;
+    }
+
+    const response = await fetch(`${this._baseUrl}${path}`, init);
+    if (!response.ok) {
+      let code = "";
+      let detail = await response.text();
+      try {
+        const payload = JSON.parse(detail);
+        code = payload.code ?? "";
+        detail = payload.detail ?? payload.title ?? detail;
+      } catch {
+        /* not JSON */
+      }
+      throw new VoiceKitError(response.status, detail, code);
+    }
+    return response;
+  }
+
+  /**
+   * Build a `ws(s)://` URL for a streaming endpoint from the base URL.
+   * @param {string} path
+   * @param {Record<string, unknown>} params
+   * @returns {string}
+   */
+  #wsUrl(path, params) {
+    const url = new URL(this._baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.pathname = path;
+    url.search = "";
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null || value === "") continue;
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+}
+
+/**
+ * @param {AudioSource} audio
+ * @returns {Promise<{ data: Uint8Array, filename: string }>}
+ */
+async function audioToParts(audio) {
+  if (audio instanceof Uint8Array) {
+    return { data: audio, filename: "audio.wav" };
+  }
+  const data = await readFile(audio);
+  return { data: new Uint8Array(data), filename: basename(audio) };
+}
+
+/**
+ * Encode audio as base64 for `batchAnalyze()`.
+ * @param {AudioSource} audio
+ * @returns {Promise<string>}
+ */
+export async function b64(audio) {
+  const { data } = await audioToParts(audio);
+  return Buffer.from(data).toString("base64");
+}
+
+/**
+ * @param {Record<string, unknown>} object
+ * @returns {Record<string, unknown>}
+ */
+function compact(object) {
+  return Object.fromEntries(
+    Object.entries(object).filter(([, value]) => value !== undefined && value !== null),
+  );
+}
+
+// ──────────────────────── WebSocket streaming ─────────────────────────
+
+/**
+ * A connected streaming session (transcription or VAD).
+ */
+export class WsStream {
+  /**
+   * @param {import("ws")} ws
+   */
+  constructor(ws) {
+    /** @private */ this._ws = ws;
+    // Prevent unhandled 'error' events from crashing the process mid-session.
+    ws.on("error", () => {});
+  }
+
+  /**
+   * Send raw PCM16 (16 kHz, mono, little-endian) audio.
+   * @param {Uint8Array} pcm16
+   * @returns {Promise<void>}
+   */
+  sendAudio(pcm16) {
+    return new Promise((resolve, reject) => {
+      this._ws.send(pcm16, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /**
+   * Send a text frame (objects are JSON-encoded).
+   * @param {unknown} payload
+   * @returns {Promise<void>}
+   */
+  sendText(payload) {
+    const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+    return new Promise((resolve, reject) => {
+      this._ws.send(text, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /**
+   * Signal end of speech so the server finalizes the utterance.
+   * @returns {Promise<void>}
+   */
+  stop() {
+    return this.sendText({ type: "stop" });
+  }
+
+  /**
+   * Receive JSON events (`session`, `vad`, `partial`, `final`, `error`).
+   * @returns {AsyncGenerator<Record<string, unknown>>}
+   */
+  async *events() {
+    for await (const message of this._ws) {
+      yield typeof message === "string" ? JSON.parse(message) : JSON.parse(message.toString("utf8"));
+    }
+  }
+
+  /** Close the session. */
+  close() {
+    this._ws.close();
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {Record<string, string>} headers
+ * @returns {Promise<WsStream>}
+ */
+async function openWsStream(url, headers) {
+  const { default: WebSocket } = await import("ws");
+  const ws = new WebSocket(url, { headers });
+  await new Promise((resolve, reject) => {
+    ws.once("open", resolve);
+    ws.once("error", reject);
+  });
+  return new WsStream(ws);
+}