nexaapi

v1.0.0

Published

2 months ago

Official Node.js/TypeScript SDK for NexaAPI — AI image generation, video generation, text-to-speech, and more. Supports Flux, Stable Diffusion, Kling, Veo, ElevenLabs, and 56+ AI models.

Downloads

nexa-ai

Official Node.js / TypeScript SDK for NexaAPI — the unified AI inference API with 56+ models for image generation, video generation, text-to-speech, music generation, and image tools.

One API key. One SDK. Access to Flux, Stable Diffusion, SDXL, Kling, Veo, Sora, ElevenLabs, Suno, and dozens more.

✨ Features

🎨 Image Generation — Flux 2 Pro/Max, SDXL, Stable Diffusion 3.5, Ideogram v2, Recraft v3, GPT-Image, Imagen 4, and more
🎬 Video Generation — Kling v3, Veo 3.1, Sora 2, Minimax, Pika 2.2, Wan 2.2, and more
🔊 Text-to-Speech — ElevenLabs v3, OpenAI TTS HD, Kokoro TTS, Gemini TTS
🎵 Music Generation — Suno v4.5, Udio v2, MusicGen, Lyria 2
🔧 Image Tools — Background removal, upscaling, face enhancement, style transfer, inpainting, outpainting
⚡ Zero Dependencies — Uses native fetch (Node.js 18+)
📦 Dual Package — ESM and CommonJS builds
🔄 Auto-Polling — Automatic async job polling with configurable timeout
🛡️ Full TypeScript — Complete type definitions for all parameters and responses
🔁 Automatic Retries — Smart retry logic for rate limits and server errors

📦 Installation

npm install nexa-ai

yarn add nexa-ai

pnpm add nexa-ai

🚀 Quick Start

import NexaAI from 'nexa-ai';

const client = new NexaAI({ apiKey: 'your-api-key' });
// Or set NEXA_API_KEY environment variable

Generate an Image

const image = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'a cat astronaut floating on the moon, photorealistic',
  width: 1024,
  height: 1024,
});

console.log(image.url);
// => https://cdn.nexa-api.com/output/abc123.png

Generate a Video

const video = await client.videos.generate({
  model: 'kling-v3-pro',
  prompt: 'a drone shot flying over misty mountains at sunrise',
  duration: 5,
  aspect_ratio: '16:9',
});

console.log(video.url);
// => https://cdn.nexa-api.com/output/vid456.mp4

Text-to-Speech

const speech = await client.audio.speech({
  model: 'elevenlabs-v3',
  text: 'Welcome to NexaAI!',
  voice: 'rachel',
});

console.log(speech.url);
// => https://cdn.nexa-api.com/output/speech789.mp3

Generate Music

const music = await client.audio.music({
  model: 'suno-v4.5',
  prompt: 'upbeat electronic dance music, 120 BPM',
  duration: 30,
});

console.log(music.url);

List Available Models

const models = await client.models.list();
console.log(`${models.length} models available`);

// Filter by type
const imageModels = await client.models.list({ type: 'image' });
const videoModels = await client.models.list({ type: 'video' });
const audioModels = await client.models.list({ type: 'audio' });

📖 API Reference

`new NexaAI(config?)`

Create a new NexaAI client.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | apiKey | string | process.env.NEXA_API_KEY | Your NexaAPI API key | | baseURL | string | https://nexa-api.com | API base URL | | timeout | number | 30000 | HTTP request timeout (ms) | | pollTimeout | number | 300000 | Max time to wait for async jobs (ms) | | pollInterval | number | 2000 | Interval between job status polls (ms) | | maxRetries | number | 2 | Max retries on transient errors | | defaultHeaders | Record<string, string> | {} | Custom headers for every request |

`client.images.generate(params)`

Generate an image from a text prompt.

const result = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'a beautiful sunset over the ocean',
  width: 1024,
  height: 1024,
  num_images: 1,
  guidance_scale: 7.5,
  steps: 30,
  seed: 42,
  output_format: 'png',
});

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | ✅ | Model ID | | prompt | string | ✅ | Text description of the image | | negative_prompt | string | | Things to avoid | | width | number | | Image width in pixels | | height | number | | Image height in pixels | | num_images | number | | Number of images to generate | | steps | number | | Inference steps | | guidance_scale | number | | CFG scale | | seed | number | | Random seed for reproducibility | | output_format | 'png' \| 'jpg' \| 'webp' | | Output format | | image_url | string | | Reference image (img2img) | | strength | number | | Reference image influence (0-1) | | lora | string | | LoRA model ID | | lora_strength | number | | LoRA strength (0-1) | | style | string | | Style preset | | wait | boolean | | Wait for completion (default: true) |

Returns: ImageGenerateResult

{
  id: string;        // Job ID
  status: JobStatus; // 'completed' | 'pending' | 'processing' | 'failed'
  url?: string;      // Generated image URL
  urls?: string[];   // Multiple image URLs
  job: Job;          // Full job object
}

`client.images.upscale(params)`

Upscale an image to higher resolution.

const result = await client.images.upscale({
  image_url: 'https://example.com/photo.jpg',
  model: 'image-upscaler-4x',
  scale: 4,
});

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | image_url | string | ✅ | URL of image to upscale | | model | string | | Upscaler model ID | | scale | number | | Scale factor | | wait | boolean | | Wait for completion (default: true) |

`client.videos.generate(params)`

Generate a video from a text prompt.

const result = await client.videos.generate({
  model: 'veo-3.1',
  prompt: 'a timelapse of flowers blooming',
  duration: 8,
  aspect_ratio: '16:9',
});

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | ✅ | Model ID | | prompt | string | ✅ | Text description | | negative_prompt | string | | Things to avoid | | width | number | | Video width | | height | number | | Video height | | duration | number | | Duration in seconds | | fps | number | | Frames per second | | image_url | string | | Input image (image-to-video) | | aspect_ratio | string | | Aspect ratio (e.g. "16:9") | | seed | number | | Random seed | | guidance_scale | number | | Guidance scale | | steps | number | | Inference steps | | wait | boolean | | Wait for completion (default: true) |

Returns: VideoGenerateResult

{
  id: string;
  status: JobStatus;
  url?: string;      // Generated video URL
  duration?: number;  // Video duration in seconds
  job: Job;
}

`client.audio.speech(params)`

Generate speech from text (text-to-speech).

const result = await client.audio.speech({
  model: 'elevenlabs-v3',
  text: 'Hello, world!',
  voice: 'rachel',
  output_format: 'mp3',
});

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | model | string | ✅ | Model ID | | text | string | | Text to speak | | input | string | | Text to speak (alias) | | voice | string | | Voice ID or name | | language | string | | Language code | | speed | number | | Speed multiplier | | output_format | 'mp3' \| 'wav' \| 'ogg' \| 'flac' | | Output format | | prompt | string | | Prompt (for music models) | | duration | number | | Duration (for music models) | | wait | boolean | | Wait for completion (default: true) |

Aliases: client.audio.tts(), client.audio.music()

Returns: AudioSpeechResult

{
  id: string;
  status: JobStatus;
  url?: string;      // Generated audio URL
  duration?: number;  // Audio duration in seconds
  job: Job;
}

`client.models.list(params?)`

List available models.

const all = await client.models.list();
const images = await client.models.list({ type: 'image' });

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | type | 'image' \| 'video' \| 'audio' \| 'tool' | | Filter by model type |

Returns: Model[]

`client.getJob(jobId)`

Get the status of a job.

const job = await client.getJob('job-abc123');
console.log(job.status); // 'pending' | 'processing' | 'completed' | 'failed'

`client.waitForJob(jobId, options?)`

Poll a job until it completes or fails.

const job = await client.waitForJob('job-abc123', {
  pollTimeout: 600_000,  // 10 minutes
  pollInterval: 5_000,   // 5 seconds
});

🎨 Supported Models

Image Generation (30+ models)

| Model | ID | |-------|----| | Flux Schnell | flux-schnell | | Flux Dev | flux-dev | | Flux Pro | flux-pro | | Flux Pro Ultra | flux-pro-ultra | | Flux 2 Pro | flux-2-pro | | Flux 2 Max | flux-2-max | | Flux 2 Flash | flux-2-flash | | Flux 2 Flex | flux-2-flex | | Flux 2 Klein | flux-2-klein | | Flux Dev LoRA | flux-dev-lora | | Flux Pro LoRA | flux-pro-lora | | Flux Kontext Pro | flux-kontext-pro | | Flux Kontext Max | flux-kontext-max | | SD 3.5 Large | sd-3.5-large | | SD 3.5 Medium | sd-3.5-medium | | SD 3.5 Turbo | sd-3.5-turbo | | SDXL | sdxl | | SDXL Lightning | sdxl-lightning | | Ideogram v2 | ideogram-v2 | | Ideogram v2 Turbo | ideogram-v2-turbo | | Recraft v3 | recraft-v3 | | GPT-Image 1.5 | gpt-image-1.5 | | Gemini 3 Pro Image | gemini-3-pro-image | | Seedream 4.5 | seedream-4.5 | | Aurora | aurora | | Playground v3 | playground-v3 | | Aura Flow | aura-flow | | Kolors | kolors | | Nano Banana | nano-banana | | Nano Banana 2 | nano-banana-2 | | Nano Banana Pro | nano-banana-pro | | Imagen 4 | imagen-4 |

Video Generation (15+ models)

| Model | ID | |-------|----| | Kling v3 Pro | kling-v3-pro | | Kling v3 Standard | kling-v3-standard | | Kling v2.5 Turbo | kling-v2.5-turbo | | Kling v2.6 Pro | kling-v2.6-pro | | Kling O3 | kling-o3 | | Kling AI Avatar | kling-ai-avatar | | Veo 3.1 | veo-3.1 | | Veo 3.1 Fast | veo-3.1-fast | | Veo 3 | veo-3 | | Sora 2 | sora-2 | | Minimax Video 01 | minimax-video-01 | | Seedance v1.5 | seedance-v1.5 | | Hunyuan Video | hunyuan-video | | CogVideoX 5B | cogvideox-5b | | LTX Video | ltx-video | | Wan 2.2 | wan-2.2 | | Pika 2.2 | pika-2.2 |

Audio & Speech (15+ models)

| Model | ID | |-------|----| | ElevenLabs v3 | elevenlabs-v3 | | ElevenLabs Turbo v3 | elevenlabs-turbo-v3 | | ElevenLabs Sound Effects | elevenlabs-sound-effects | | ElevenLabs Music | elevenlabs-music | | OpenAI TTS HD | openai-tts-hd | | OpenAI TTS Standard | openai-tts-standard | | Kokoro TTS | kokoro-tts | | Gemini TTS | gemini-tts | | Whisper v3 Turbo | whisper-v3-turbo | | Deepgram Nova 3 | deepgram-nova-3 | | AssemblyAI Universal 2 | assemblyai-universal-2 | | Suno v4.5 | suno-v4.5 | | Udio v2 | udio-v2 | | MusicGen Large | musicgen-large | | AudioCraft Stereo | audiocraft-stereo | | Lyria 2 | lyria-2 |

Image Tools

| Tool | ID | |------|----| | Background Removal | background-removal | | Image Upscaler 4x | image-upscaler-4x | | SeedVR2 Upscaler | seedvr2-upscaler | | Face Enhancement | face-enhancement | | Style Transfer | style-transfer | | Inpainting | inpainting | | Outpainting | outpainting | | Object Removal | object-removal | | Colorization | colorization |

⚡ Advanced Usage

Fire-and-Forget (No Waiting)

const result = await client.images.generate({
  model: 'flux-2-pro',
  prompt: 'a beautiful landscape',
  wait: false, // Returns immediately with job ID
});

console.log('Job ID:', result.id);
console.log('Status:', result.status); // 'pending'

// Check later
const job = await client.getJob(result.id);
if (job.status === 'completed') {
  console.log('Image URL:', job.result?.url);
}

Custom Polling

const client = new NexaAI({
  apiKey: 'your-key',
  pollTimeout: 600_000,  // 10 minutes for video generation
  pollInterval: 5_000,   // Check every 5 seconds
});

Manual Job Polling

const result = await client.videos.generate({
  model: 'veo-3.1',
  prompt: 'epic cinematic scene',
  wait: false,
});

// Poll with custom options
const completed = await client.waitForJob(result.id, {
  pollTimeout: 600_000,
  pollInterval: 10_000,
});

console.log('Video URL:', completed.result?.url);

Error Handling

import NexaAI, {
  AuthenticationError,
  RateLimitError,
  ValidationError,
  PollTimeoutError,
  APIError,
} from 'nexa-ai';

try {
  const result = await client.images.generate({
    model: 'flux-2-pro',
    prompt: 'test',
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof ValidationError) {
    console.error('Invalid parameters:', error.message);
  } else if (error instanceof PollTimeoutError) {
    console.error(`Job ${error.jobId} timed out (last status: ${error.lastStatus})`);
  } else if (error instanceof APIError) {
    console.error(`API error ${error.status}: ${error.message}`);
  }
}

Environment Variable

export NEXA_API_KEY=your-api-key

// No need to pass apiKey when env var is set
const client = new NexaAI();

CommonJS

const { NexaAI } = require('nexa-ai');

const client = new NexaAI({ apiKey: 'your-key' });

🔗 Links

Website: https://nexa-api.com
API Documentation: https://nexa-api.com/docs
Dashboard: https://nexa-api.com/dashboard
GitHub: https://github.com/nexa-api/nexa-ai-node
npm: https://www.npmjs.com/package/nexa-ai
RapidAPI: https://rapidapi.com/nexa-api

🔑 Getting an API Key

Visit https://nexa-api.com
Create an account or sign in
Navigate to the Dashboard → API Keys
Generate a new API key
Use it in the SDK or set NEXA_API_KEY environment variable

📋 Requirements

Node.js 18+ (uses native fetch)
TypeScript 5.0+ (optional, for type checking)