Перейти к содержимому
NexusAPI Docs

SDK

Официальные SDK для удобной интеграции — без ручной возни с HTTP. Под капотом используется тот же native /generate + /tasks/{id} flow, но с типизированными объектами, polling-helper’ами и осмысленными исключениями.

Установка

Окно терминала
pip install nexusapi-sdk

Требования: Python 3.9+. Импорт остаётся from nexusapi import ... — distribution-имя на PyPI отличается от import-имени (так же как pip install scikit-learn → import sklearn).

Quickstart

from nexusapi import NexusClient


client = NexusClient(api_key="ВАШ_КЛЮЧ")


# Изображение (SDK сам ждёт до завершения)
img = client.images.generate(
    model="nano-banana",
    prompt="Минималистичный логотип кофейни",
    aspect_ratio="1:1",
)
print(img.image_url)


# Видео (async — получаем Task, ждём отдельно)
task = client.videos.create(
    model="veo-3-fast",
    prompt="Кот играет на пианино",
    duration=8,
    aspect_ratio="16:9",
)
task.wait(timeout=600)
print(task.video_url)

Async (Python)

Для FastAPI / aiohttp / любого asyncio-приложения — используй AsyncNexusClient вместо NexusClient. Публичный API идентичен, разница только в await:

import asyncio
from nexusapi import AsyncNexusClient


async def main():
    async with AsyncNexusClient(api_key="...") as client:
        task = await client.videos.create(
            model="veo-3-fast", prompt="a cat", duration=8,
        )
        await task.wait()
        print(task.video_url)


asyncio.run(main())

В Node SDK всё уже async — отдельного варианта не нужно.

Reliability (retries + idempotency)

Оба SDK поставляются с production-grade reliability по умолчанию:

  • Auto-retries на 5xx, 429 и сетевые ошибки. До 3 попыток (1 initial + 2 retry) с экспоненциальным backoff (~0.5s, 1s, 2s + jitter). Учитывает Retry-After header. Настройка: max_retries=N (Python) / maxRetries: N (Node), 0 для отключения.
  • Auto Idempotency-Key — для каждого POST автоматически генерируется sdk-<uuid> ключ, если клиент не передал свой. Это делает retry’и безопасными — двойного списания не будет. Своё значение тоже можно передать (например, ключ заказа из своей БД) через idempotency_key / idempotencyKey. Подробнее — Идемпотентность.

API

NexusClient(api_key, base_url=..., max_retries=2) / AsyncNexusClient(...)

Главный клиент. api_key — Bearer-токен из panel.nexusapi.dev. base_url опциональный (дефолт https://nexusapi.dev). max_retries — сколько раз повторить запрос при 5xx/429/network-ошибках (дефолт 2).

client.videos.create(model, prompt, duration, **extras) → Task

Создаёт видео-задачу. Возвращает Task в pending сразу — для ожидания используй task.wait(). Параметры конкретной модели передавай как обычные kwargs (Python) или поля объекта (Node) — пройдут в native params:

task = client.videos.create(
    model="kling-v2.6-motion-1080p",
    prompt="Камера отъезжает назад",
    duration=8,
    image_url="https://...",          # native параметр для motion-моделей
    negative_prompt="blur",            # native
    webhook_url="https://app/cb",     # native
)

client.images.generate(model, prompt, wait=True, **extras) → Task

То же что videos.create, но по умолчанию ждёт завершения (sync UX — image-модели быстрые, 10-60 секунд). Передай wait=False если хочешь polling вручную.

client.tasks.get(task_id) → Task

Получает текущее состояние задачи по ID. Удобно если task_id получен через webhook.

client.models.list() → list

Каталог активных моделей с ценами. Не требует auth (использует публичный /public/models).

Task

task.id              # UUID
task.status          # pending | processing | completed | failed
task.is_done         # bool
task.video_url       # str | None (для видео-моделей)
task.image_url       # str | None (для image-моделей — первое из image_urls)
task.image_urls      # list[str] (для multi-image моделей)
task.error           # str | None (заполнено если status=failed)
task.result          # dict — сырой ответ провайдера
task.refresh()       # GET /tasks/{id}, обновляет поля
task.wait(timeout, poll_interval)  # block до completed/failed

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

Все SDK-исключения наследуются от NexusError. Можно ловить как общий класс или конкретные:

from nexusapi import (
    NexusClient,
    BillingError,       # 402 — баланса не хватает
    RateLimitError,     # 429 — превышен rate_limit_per_min ключа
    ValidationError,    # 400/422 — невалидные параметры
    NexusPermissionError,  # 403 — restrictions ключа
    NotFoundError,      # 404 — task/model не найдены
    NexusTimeoutError,  # task.wait() не дождался
    NexusError,         # базовый класс
)


try:
    task = client.videos.create(model="veo-3-fast", prompt="...", duration=8)
    task.wait()
except BillingError:
    print("Пополни баланс")
except RateLimitError:
    print("Подожди минуту")
except ValidationError as e:
    print(f"Невалидные параметры: {e}")

Webhook вместо polling

Если не хочешь блокировать поток на task.wait() — передай webhook_url, сохрани task.id, и обрабатывай результат в callback’е.

task = client.videos.create(
    model="veo-3-fast",
    prompt="...",
    duration=8,
    webhook_url="https://your-app.com/nexus-callback",
)
save_to_db(task.id)  # NexusAPI POST'нет на webhook когда видео готово

См. Webhooks для деталей retry-логики и idempotency.

Дистрибутивы