Meet the NeoSpeech Node.js SDK

Developers asked for a first-class JavaScript experience, and now it is here. The NeoSpeech Node.js SDK makes it simple to turn text into engaging audio across more than 50 voices in 90+ languages. Whether you are building a voice-enabled app, powering customer support, or automating media creation, the SDK gives you a modern, type-safe interface to the NeoSpeech Text-to-Speech API.

Why a Dedicated Node.js SDK Matters

JavaScript developers have been connecting to NeoSpeech through raw HTTP calls, but that approach adds boilerplate, authentication handling, and brittle error management. The official SDK packages these concerns in a single dependency that you can drop into any Node.js 18+ project.

• Faster iteration: Instantiate the client once, then call readable methods like audio.speech or audio.stream.
• Consistency across stacks: A shared API surface mirrors our REST endpoints, so your backend and frontend teams stay aligned.
• Production readiness: Automatic retries, helpful error primitives, and TypeScript definitions reduce the risk of surprises in production.

Installation and Setup

Add the SDK to your project with npm, pnpm, or yarn. Authentication uses your dashboard API key, which is required for Pro and Business plans.

npm install neospeech-io

import NeoSpeech from "neospeech-io";

const neospeech = new NeoSpeech(process.env.NEOSPEECH_API_KEY!);

Configuration options let you adjust the base URL, timeouts, or retry strategy:

const neospeech = new NeoSpeech(process.env.NEOSPEECH_API_KEY!, {
  baseURL: "https://api.neospeech.io/v1",
  timeout: 120_000,
  maxRetries: 3,
});

Quick Start: Generate Speech in Seconds

The SDK exposes ergonomic methods for generating audio buffers that you can save, stream, or pipe directly to a response.

const audio = await neospeech.audio.speech({
  input: "Hello, world!",
  voice: "lyra",
  model: "aurora-4",
});

await fs.promises.writeFile("hello.mp3", Buffer.from(audio));

Need to transform multiple utterances? Kick off a batch of promises and wait for them to finish.

async function batchGenerate(texts: string[], voice = "kai", model = "turbo-3") {
  return Promise.all(
    texts.map((input) => neospeech.audio.speech({ input, voice, model }))
  );
}

Stream Speech for Live Experiences

When latency is critical—think interactive agents or live dubbing—you can request a readable stream instead of a single buffer. The SDK forwards a standard ReadableStream, so you can progressively play or transcode audio as it arrives.

const stream = await neospeech.audio.stream({
  input: "This is streaming audio",
  voice: "kai",
  model: "turbo-3",
});

const chunks: Uint8Array[] = [];
const reader = stream.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

await fs.promises.writeFile("stream.mp3", Buffer.concat(chunks.map(Buffer.from)));

Fine-Tune Every Voice

NeoSpeech voices support pitch, style, language, and model tweaks so you can match outputs to your brand or use case.

await neospeech.audio.speech({
  input: "Professional narration",
  voice: "emma",
  model: "aurora-3.5",
  pitch: "+10%",
  style: "cheerful",
  styleDegree: "1.5",
  lang: "en-US",
});

Pull the latest catalog when you need to explore options or build voice selectors inside your UI.

const { voices, pagination } = await neospeech.voices.list({
  search: "lyra",
  gender: "female",
  locale: "en-US",
  limit: 10,
});

The same approach works for models:

const { models } = await neospeech.models.list();
models.forEach((model) => {
  console.log(`${model.name}: ${model.quality} quality`);
});

Built-In Error Insights

Every request can throw a NeoSpeechError, which carries metadata for smarter retries or user messaging.

import { NeoSpeechError } from "neospeech-io";

try {
  await neospeech.audio.speech({ input: "Test", voice: "lyra" });
} catch (error) {
  if (error instanceof NeoSpeechError) {
    console.error(`Error [${error.code}]: ${error.message}`);
    if (error.isAuthError()) {
      console.error("Check your API key");
    } else if (error.isRateLimitError()) {
      console.error("Rate limit exceeded");
    }
  }
}

Helper methods like isClientError, isServerError, and retryable flags make it obvious whether to show a user-friendly message or schedule a retry with exponential backoff.

async function generateWithRetry(text: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt += 1) {
    try {
      return await neospeech.audio.speech({ input: text, voice: "lyra", model: "aurora-4" });
    } catch (error) {
      if (error instanceof NeoSpeechError && error.retryable && attempt < maxRetries - 1) {
        const delay = 2 ** attempt * 1000;
        await new Promise((resolve) => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Designed for Modern TypeScript

While the SDK works out of the box with CommonJS, it also ships with TypeScript definitions. Strong typing covers request payloads, responses, and error surfaces so you can rely on autocomplete instead of constantly checking docs.

import NeoSpeech, { SpeechOptions } from "neospeech-io";

const options: SpeechOptions = {
  input: "Hello, TypeScript!",
  voice: "lyra",
  model: "aurora-4",
};

const audio = await neospeech.audio.speech(options);

What You Need to Get Started

• Node.js 18 or newer
• A NeoSpeech API key from your dashboard
• Access to the Pro or Business plan for production usage

With those pieces in place, you can be generating production-ready speech within minutes.

Build Your Next Voice Experience

The NeoSpeech Node.js SDK is available today on npm as neospeech-io. Install it, plug in your API key, and start experimenting with new voice-first experiences for support bots, interactive demos, learning tools, and beyond. If you have feedback or feature requests, reach out through support@neospeech.io or open an issue on GitHub—we are eager to hear what you build.