Aisha AI Node.js SDK

aisha-ai is the Node.js SDK for the Aisha AI API.

Use it when you want to add text-to-speech or speech-to-text to a Node.js, Express, NestJS, Fastify, or backend service.

import { AishaClient } from "aisha-ai";

const client = new AishaClient({ apiKey: process.env.AISHA_API_KEY! });
const result = await client.tts({ transcript: "Salom dunyo" });

console.log(result.audioUrl);

Contents

• Features
• Requirements
• Install
• Quick Start
• API Versions
• Server Integration Flow
• Client Setup
• Text-to-Speech
• Speech-to-Text
• History
• Parameter Reference
• SDK Constants
• Error Handling
• Optional CLI
• Development
• Continuous Integration
• Publishing
• Official API Docs

Features

• Text-to-speech (TTS)
• Speech-to-text (STT)
• TTS and STT history
• Sync TTS requests
• Async TTS requests with webhook callbacks
• Save generated TTS audio to a local path
• TypeScript types included
• ESM and CommonJS builds
• No runtime dependencies

Requirements

• Node.js 18 or newer
• An Aisha AI API key

Create an API key at space.aisha.group.

Install

npm install aisha-ai

Quick Start

Set your API key:

export AISHA_API_KEY="your-api-key"

Use the SDK:

import { AishaClient } from "aisha-ai";

const client = new AishaClient({ apiKey: process.env.AISHA_API_KEY! });

const result = await client.tts({ transcript: "Salom dunyo" });
console.log(result.audioUrl);

CommonJS also works:

const { AishaClient } = require("aisha-ai");

API Versions

This SDK defaults to Aisha API v1.

| Feature | API version | SDK methods | | -------------------- | ----------- | -------------------------------------- | | TTS sync and async | API v1 | tts(), ttsStatus(), ttsHistory() | | STT short-audio sync | API v1 | stt(), sttHistory() |

You can choose another API version when creating the client:

const client = new AishaClient({
  apiKey: process.env.AISHA_API_KEY!,
  apiVersion: "v2",
});

You can also pass apiVersion: 2; the SDK normalizes it to "v2". Existing SDK methods then call /api/v2/... paths. Only switch versions for endpoints that are supported by the Aisha API version you are integrating with.

Server Integration Flow

For server-to-server traffic, Aisha uses the X-Api-Key header. The SDK sends this header for every request:

X-Api-Key: your-api-key

Recommended backend integration flow:

1. Create an API key in Space.
2. Send a small test TTS or STT request.
3. Confirm the response shape your app needs.
4. For async TTS, store the returned id or task_id.
5. Use status and history endpoints to cover the full workflow.

Example:

const queued = await client.tts({
  transcript: "Webhook orqali qaytadigan sinov matni.",
  webhookUrl: "https://example.com/webhooks/tts",
});

const status = await client.ttsStatus(queued.id!);
const history = await client.ttsHistory({ page: 1, limit: 10 });

Client Setup

Create a client:

import { AishaClient } from "aisha-ai";

const client = new AishaClient({ apiKey: "your-api-key" });

Set the response language for API messages:

const client = new AishaClient({
  apiKey: "your-api-key",
  language: "uz",
});

Use a custom API base URL:

const client = new AishaClient({
  apiKey: "your-api-key",
  baseUrl: "https://back.aisha.group",
});

Use a different API version:

const client = new AishaClient({
  apiKey: "your-api-key",
  apiVersion: "v2",
});

Change request timeout:

const client = new AishaClient({
  apiKey: "your-api-key",
  timeoutMs: 60_000,
});

Text-to-Speech

Basic TTS

By default, TTS returns the generated audio URL. It does not download the file:

const result = await client.tts({
  transcript: "Assalomu alaykum",
});

console.log(result.audioUrl);

Save TTS Audio to a File

Pass outputPath when you want the SDK to download the generated audio:

const result = await client.tts({
  transcript: "Assalomu alaykum",
  outputPath: "outputs/assalomu-alaykum.wav",
});

console.log(result.audioUrl);
console.log(result.outputPath);

The SDK creates parent folders when needed. If you do not pass outputPath, the SDK only returns the URL and does not write anything to disk. When downloading, the SDK sends the same API key header plus a normal SDK User-Agent, so protected audio URLs can be fetched from backend services and CI jobs.

You can also download an existing audio URL later:

await client.downloadAudio(result.audioUrl!, "outputs/from-url.wav");

Uzbek TTS Options

For Uzbek TTS, you can pass model, mood, and speed:

const result = await client.tts({
  transcript: "Assalomu alaykum",
  language: "uz",
  model: "Gulnoza",
  mood: "Happy",
  speed: 1.0,
});

Known mood values:

• Neutral
• Cheerful
• Happy
• Sad

Default model:

• Gulnoza

Speed:

• 0 uses the API default speed
• 0.5 is slower
• 1.0 is normal speed
• 2.0 is faster

The SDK sends model, mood, and speed only when language: "uz".

English or Russian TTS

const english = await client.tts({
  transcript: "Hello",
  language: "en",
});

const russian = await client.tts({
  transcript: "Privet",
  language: "ru",
});

Async TTS with Webhook

Pass webhookUrl when you want the API to process TTS in the background:

const queued = await client.tts({
  transcript: "Salom dunyo",
  webhookUrl: "https://example.com/aisha-webhook",
});

console.log(queued.id);
console.log(queued.status);

Check the task later:

const status = await client.ttsStatus(queued.id!);
console.log(status);

Use outputPath only for sync TTS. Async TTS returns task information first, so there is no completed audio file to download immediately.

Speech-to-Text

Transcribe a File Path

const result = await client.stt({ file: "meeting.wav" });
console.log(result.transcript);

Transcribe a Buffer

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

const data = await readFile("meeting.wav");
const result = await client.stt({
  file: data,
  filename: "meeting.wav",
});

console.log(result.transcript);

Enable Diarization

Use diarization when you want speaker separation:

const result = await client.stt({
  file: "meeting.wav",
  diarization: true,
});

When diarization is enabled, the API expects audio to be at least 15 seconds long.

History

List past TTS requests:

const ttsHistory = await client.ttsHistory({ page: 1, limit: 10 });

List past STT requests:

const sttHistory = await client.sttHistory({ page: 1, limit: 10 });

page and limit must be positive integers.

Parameter Reference

new AishaClient(...)

| Parameter | Type | Default | Description | | ------------ | ------------------ | -------------------------- | ----------------------------------- | | apiKey | string | required | API key from space.aisha.group. | | baseUrl | string | https://back.aisha.group | API base URL. | | apiVersion | string \| number | v1 | API version used in endpoint paths. | | language | uz \| en \| ru | undefined | API message language. | | timeoutMs | number | 120000 | Request timeout in milliseconds. |

client.tts(...)

| Parameter | Type | Default | Description | | ------------ | ------------------ | --------- | ---------------------------------------------- | | transcript | string | required | Text to turn into speech. Max 1000 characters. | | language | uz \| en \| ru | uz | Voice language. | | model | string | Gulnoza | Uzbek TTS voice model. | | mood | string | Neutral | Uzbek TTS mood. | | speed | number \| string | 1.0 | Uzbek TTS speed: 0, or 0.5 to 2.0. | | webhookUrl | string | undefined | Webhook URL for async TTS. | | outputPath | string \| URL | undefined | Local path where audio should be saved. |

client.stt(...)

| Parameter | Type | Default | Description | | ------------- | --------------------------------------------------- | ----------- | ------------------------------------------ | | file | path, URL, Blob, ArrayBuffer, Uint8Array, or Buffer | required | Audio file to transcribe. | | language | uz \| en \| ru | uz | Audio language. | | diarization | boolean | false | Enables speaker diarization. | | filename | string | audio.wav | File name used when passing bytes or Blob. |

SDK Constants

You can import common values:

import {
  DEFAULT_API_VERSION,
  DEFAULT_TTS_MODEL,
  DEFAULT_TTS_MOOD,
  DEFAULT_TTS_SPEED,
  MAX_TTS_TRANSCRIPT_LENGTH,
  STT_API_VERSION,
  SUPPORTED_AUDIO_FORMATS,
  SUPPORTED_LANGUAGES,
  TTS_API_VERSION,
  TTS_MOODS,
} from "aisha-ai";

Current values:

| Name | Value | | --------------------------- | ----------------------------------------- | | DEFAULT_API_VERSION | "v1" | | SUPPORTED_LANGUAGES | ["uz", "en", "ru"] | | TTS_API_VERSION | "v1" | | STT_API_VERSION | "v1" | | SUPPORTED_AUDIO_FORMATS | ["mp3", "wav", "ogg", "m4a"] | | TTS_MOODS | ["Neutral", "Cheerful", "Happy", "Sad"] | | DEFAULT_TTS_MODEL | "Gulnoza" | | DEFAULT_TTS_MOOD | "Neutral" | | DEFAULT_TTS_SPEED | 1.0 | | MIN_TTS_SPEED | 0.5 | | MAX_TTS_SPEED | 2.0 | | MAX_TTS_TRANSCRIPT_LENGTH | 1000 |

Error Handling

The SDK raises AishaApiError when the API returns an error response:

import { AishaApiError, AishaClient } from "aisha-ai";

try {
  const result = await client.tts({ transcript: "Salom" });
} catch (error) {
  if (error instanceof AishaApiError) {
    console.log(error.status);
    console.log(error.body);
    console.log(error.url);
  }
}

Network failures raise AishaConnectionError. It is a subclass of AishaApiError, so one catch block can handle both API and network failures.

For connection errors:

• error.status is 0
• error.body is null

Optional CLI

The package also installs an aisha-ai command. It is useful for quick manual tests, demos, or simple scripts. For applications, prefer importing AishaClient in JavaScript or TypeScript.

export AISHA_API_KEY="your-api-key"

aisha-ai tts "Salom dunyo" --out salom.wav
aisha-ai stt meeting.wav
aisha-ai history tts --page 1 --limit 10

Development

Install dependencies:

npm install

Run all local checks:

npm run verify

Individual checks:

npm run lint
npm run format:check
npm run typecheck
npm test
npm run build
npm pack --dry-run

Real API smoke tests are disabled by default. To run them manually:

export AISHA_API_TEST_KEY="your-real-test-key"
npm run test:real

Continuous Integration

Pull requests and pushes to main run GitHub Actions CI.

The quality job checks:

• ESLint
• Prettier formatting
• TypeScript type checking

The test job checks:

• package installation
• unit tests with the local mock API server
• Node.js 18, 20, 22, and 24

The package job checks:

• production build
• npm pack --dry-run

The real API smoke test job runs after quality checks, unit tests, and package build. It uses the repository secret AISHA_API_TEST_KEY and checks:

• a few short TTS requests with different Uzbek options
• downloading one generated audio file with outputPath
• TTS history response shape
• a few edge cases

Publishing

Publishing is separate from normal merges:

• Pull requests test the code before merge.
• Pushes to main test and build the package.
• Version tags like v1.0.1 publish to npm after CI passes.

Release flow:

git checkout main
git pull
git tag v1.0.1
git push origin v1.0.1

Official API Docs

• TTS API: https://aisha.group/en/api-documentation/text-to-speech
• STT API: https://aisha.group/en/api-documentation/speech-to-text
• API keys: https://space.aisha.group