nexusapi-sdk 0.2.0

Python SDK для NexusAPI — генерация видео и изображений через единый API (Veo, Kling, Seedance, Nano-Banana). Sync + async, auto-retries, auto idempotency.

NexusAPI Python SDK

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

Установка

pip install nexusapi-sdk

Пакет на PyPI называется nexusapi-sdk (имя nexusapi зарезервировано похожим проектом). Импорт остаётся from nexusapi import ....

Quickstart — sync

from nexusapi import NexusClient

with NexusClient(api_key="ВАШ_КЛЮЧ") as client:  # создать в panel.nexusapi.dev
    # Изображение (sync — SDK сам опрашивает статус)
    img = client.images.generate(
        model="nano-banana",
        prompt="Минималистичный логотип кофейни",
        aspect_ratio="1:1",
    )
    print(img.image_url)
    # → https://nexusapi-s3.../result.png

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

Quickstart — async (FastAPI / aiohttp / asyncio)

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="Кот играет на пианино",
            duration=8,
        )
        await task.wait()
        print(task.video_url)

asyncio.run(main())

Публичный API идентичен sync — все методы те же, отличается только await.

Возможности

• Sync (NexusClient) и async (AsyncNexusClient) — одинаковый API, можно использовать в скриптах или внутри FastAPI/aiohttp без блокировки event loop.
• Auto-retries — на 5xx, 429 и сетевые ошибки. По умолчанию до 3 попыток с экспоненциальным backoff (0.5s, 1s, 2s + jitter). Учитывает Retry-After header. Настраивается через max_retries=N.
• Auto Idempotency-Key — для каждого POST автоматически генерируется UUID v4 если не передан свой. Retry безопасен — двойного списания не будет.
• Все native-параметры через **kwargs — 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, NexusPermissionError, NexusTimeoutError (client-side wait timeout), TaskFailedError (провайдер не справился), NetworkError (retries исчерпаны).
• Context manager — with NexusClient(...) as c: / async with AsyncNexusClient(...) as c: закрывает HTTP-соединение автоматически.

Примеры

Webhook вместо polling

task = 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)

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

Image edit (nano-banana)

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

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

task = client.videos.create(...).wait()
print(task.video_url)        # для видео-моделей
print(task.image_url)        # для image-моделей (берёт первое из image_urls)
print(task.image_urls)       # для image-моделей с несколькими изображениями
print(task.result)           # сырой dict с провайдер-специфичным контентом

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

from nexusapi import NexusClient, BillingError, RateLimitError, ValidationError

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

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

models = client.models.list()
for m in models:
    print(f"{m['id']}: {m['priceRub']}₽ за {m['unit']}")

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

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

Лицензия

MIT