NexusAPI Node.js SDK

Официальный Node.js / TypeScript SDK для NexusAPI — единый API для генерации видео и изображений через Veo, Kling, Seedance, Nano-Banana и др.

Установка

npm install nexusapi-sdk

Требует Node.js 18+ (используем встроенный fetch). Без внешних зависимостей.

Пакет на npm называется nexusapi-sdk (имя nexusapi зарезервировано другим проектом). Mirror Python SDK: pip install nexusapi-sdk.

Quickstart

import { NexusClient } from "nexusapi-sdk";

const client = new NexusClient({
  apiKey: process.env.NEXUS_KEY!,  // создать в panel.nexusapi.dev
});

// Изображение (sync — SDK сам опрашивает статус)
const img = await client.images.generate({
  model: "nano-banana",
  prompt: "Минималистичный логотип кофейни",
  aspect_ratio: "1:1",
});
console.log(img.imageUrl);
// → https://nexusapi-s3.../result.png

// Видео (async — получаем Task, ждём отдельно)
const task = await client.videos.create({
  model: "veo-3-fast",
  prompt: "Кот играет на пианино",
  duration: 8,
  aspect_ratio: "16:9",
});
console.log(`Task ${task.id}, status=${task.status}`);

// Polling до завершения (до 10 минут)
await task.wait();
console.log(task.videoUrl);

Возможности

• Auto-retries — на 5xx, 429 и сетевые ошибки. По умолчанию до 3 попыток с экспоненциальным backoff (0.5s, 1s, 2s + jitter). Учитывает Retry-After header. Настраивается через maxRetries: N в опциях клиента.
• Auto Idempotency-Key — для каждого POST автоматически генерируется UUID v4 если не передан свой. Retry безопасен — двойного списания не будет.
• Все native-параметры — webhook_url, negative_prompt, image_url, cfg_scale, video_urls для seedance, source_video_url для veo-extend передаются прямо в create() / generate() как обычные поля объекта.
• Auto-polling для image-моделей (sync UX). Для видео — task.wait().
• Типизированные ошибки — NexusError (база), BillingError, RateLimitError, ValidationError, NotFoundError, AuthenticationError, PermissionError, TaskTimeoutError (client-side wait), TaskFailedError (провайдер не справился), NetworkError (retries исчерпаны).
• TypeScript-first — полные типы для всех методов.
• Zero dependencies — только native fetch Node 18+.

Примеры

Webhook вместо polling

const task = await client.videos.create({
  model: "veo-3-fast",
  prompt: "...",
  duration: 8,
  webhook_url: "https://your-app.com/nexus-callback",
});
// Не вызываем .wait() — NexusAPI POST'нет на webhook_url когда видео готово
return task.id;  // сохраняем в БД, ждём колбэка

Image-to-video (Kling motion)

const video = await client.videos.create({
  model: "kling-v2.6-motion-1080p",
  prompt: "Камера медленно отъезжает, раскрывая пейзаж",
  duration: 8,
  image_url: "https://your-bucket.s3.../start-frame.jpg",
});
await video.wait();
console.log(video.videoUrl);

Image edit (nano-banana)

const edited = await client.images.generate({
  model: "nano-banana-pro",
  prompt: "Сделай небо более драматичным",
  image_url: "https://your-bucket.s3.../photo.jpg",
});
console.log(edited.imageUrl);

Извлечение результата

const task = await client.videos.create({ ... });
await task.wait();
console.log(task.videoUrl);       // для видео-моделей
console.log(task.imageUrl);       // для image-моделей (берёт первое из imageUrls)
console.log(task.imageUrls);      // для image-моделей с несколькими изображениями
console.log(task.result);         // сырой объект с провайдер-специфичным контентом

Обработка ошибок

import {
  NexusClient,
  BillingError,
  RateLimitError,
  ValidationError,
} from "nexusapi-sdk";

try {
  const task = await client.videos.create({ ... });
  await task.wait();
} catch (e) {
  if (e instanceof BillingError) {
    console.error("Недостаточно средств");
  } else if (e instanceof RateLimitError) {
    console.error("Превышен rate-limit");
  } else if (e instanceof ValidationError) {
    console.error("Невалидные параметры:", e.message);
  } else {
    throw e;
  }
}

Каталог моделей

const models = await client.models.list();
for (const m of models) {
  console.log(`${m.id}: ${m.priceRub}₽ за ${m.unit}`);
}

Документация

• docs.nexusapi.dev — гайды и каталог моделей
• docs.nexusapi.dev/api-reference — полный API reference
• docs.nexusapi.dev/models — параметры каждой модели

Лицензия

MIT