API Reference

Полный справочник публичных эндпоинтов NexusAPI для интеграции через API-ключ.

Базовый URL: https://nexusapi.dev

Аутентификация

Все запросы — Bearer-токен с API-ключом из panel.nexusapi.dev:

Authorization: Bearer <ВАШ_API_KEY>

Исключение — каталог моделей /public/models и OpenAI-совместимые алиасы /v1/models, они без auth. Подробнее — Аутентификация.

---

Генерация

Основной flow: создаёшь задачу → ждёшь результат. Полное описание async-модели — на странице Задачи и статусы.

POST /generate

Создаёт новую задачу генерации. Hold стоимости на ключе происходит в той же транзакции, что и создание задачи — либо оба, либо ничего.

Заголовки: Authorization: Bearer <api_key>, Content-Type: application/json

Тело:

{
  "params": {
    "model_name": "veo-3-fast",
    "prompt": "Кот играет на пианино",
    "duration": 8,
    "aspect_ratio": "16:9",
    "webhook_url": "https://your-app.com/callback"
  }
}

Поле params оборачивает все параметры модели. Обязательное только model_name (полный список — в каталоге); остальные зависят от модели.

Возвращает 202 Accepted:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000"
}

Ошибки:

• 401 — ключ не передан или невалидный
• 402 — баланса не хватает на стоимость модели
• 403 — IP не в allowlist ключа, или модель не в allowed_models
• 404 — модель неактивна
• 422 — model_name отсутствует или цена на модель не установлена
• 429 — превышен rate_limit_per_min ключа
• 503 — включён maintenance-режим

curl

curl -X POST https://nexusapi.dev/generate \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "model_name": "veo-3-fast",
      "prompt": "Кот играет на пианино",
      "duration": 8,
      "aspect_ratio": "16:9"
    }
  }'

Python

resp = requests.post(
    "https://nexusapi.dev/generate",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"params": {
        "model_name": "veo-3-fast",
        "prompt": "Кот играет на пианино",
        "duration": 8,
        "aspect_ratio": "16:9",
    }},
)
task_id = resp.json()["task_id"]

GET /tasks/{task_id}

Возвращает текущий статус задачи и результат при completed.

Заголовки: Authorization: Bearer <api_key>

Возвращает 200:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "result": {
    "video_url": "https://s3.amazonaws.com/.../result.mp4",
    "duration": 8
  },
  "error": null,
  "created_at": "2026-05-30T12:34:56.123Z"
}

status — одно из pending, processing, completed, failed. См. Задачи и статусы.

Ошибки:

• 401 — ключ не передан или невалидный
• 403 — задача принадлежит другому юзеру (этот ключ её не видит)
• 404 — задачи с таким ID нет
• 503 — maintenance-режим

GET /me/keys

Возвращает аккаунт владельца ключа со всеми его API-ключами. Используется ключ из Bearer-токена, чтобы найти клиента.

Возвращает 200:

{
  "telegram_id": 12345,
  "coefficient": 1.0,
  "keys": [
    { "id": 77, "key_value": "e6672505-1d47-...", "balance": 950.50 }
  ]
}

GET /me/balance

Возвращает баланс ключа, переданного в Bearer-заголовке. Удобно для отображения остатка прямо в твоём интерфейсе.

Возвращает 200:

{ "key_balance": 950.50 }

---

Текстовые модели

POST /v1/chat/completions

OpenAI-совместимый endpoint для всех активных Claude и GPT моделей. Поддерживает messages, max_tokens (или max_completion_tokens), stream, tools и tool_choice.

curl -X POST https://nexusapi.dev/v1/chat/completions \
  -H "Authorization: Bearer $NEXUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Привет"}],
    "max_tokens": 1000
  }'

Для потокового ответа передай "stream": true; ответ приходит как SSE. Полный список моделей, цены в рублях и пример tool calling — на странице Текстовые модели и в разделе OpenAI-совместимый API.

---

Каталог (без аутентификации)

GET /public/models

Список активных моделей с ценами в рублях. Подходит для отрисовки прайса/каталога в стороннем UI.

Без аутентификации.

Возвращает 200:

[
  {
    "id": "veo-3-fast",
    "name": "Veo 3 Fast",
    "provider": "nexus",
    "kind": "video",
    "unit": "shot",
    "priceRub": 50.0
  },
  {
    "id": "kling-v2.6",
    "name": "Kling V2.6",
    "provider": "nexus",
    "kind": "video",
    "unit": "sec",
    "priceRub": 9.5
  }
]

Поле unit:

• "shot" — цена за одну генерацию (priceRub × 1 = hold)
• "sec" — цена за секунду видео (priceRub × duration = hold)

Виртуальные billing-ключи seedance (типа seedance-2.0:1080p:with_video) в этот список не попадают — отдаются только видимые модели.

---

Универсальные коды ответа

Применяются к большинству эндпоинтов:

Код	Когда
200 OK	GET вернул данные
202 Accepted	Async-задача принята в обработку (POST /generate)
400 Bad Request	Невалидное тело: отсутствуют обязательные параметры
401 Unauthorized	API-ключ не передан, неверный или удалён
402 Payment Required	Баланса не хватает на стоимость модели
403 Forbidden	Чужая задача, IP не в allowlist, модель не в allowed_models
404 Not Found	task_id или модель не существует
422 Unprocessable Entity	Параметры модели не прошли валидацию
429 Too Many Requests	Превышен rate_limit_per_min ключа
503 Service Unavailable	Включён maintenance-режим

См. Ошибки — детали и рекомендации по обработке.