Задачи и статусы

NexusAPI работает только асинхронно. Любой /generate сразу возвращает task_id со статусом pending, а результат становится доступен через polling или webhook через несколько секунд (изображение) или минут (видео).

Это сознательное решение: HTTP-таймауты на 10-минутном veo-extend не имеют смысла, а одна async-модель проще, чем dual-mode endpoint.

Жизненный цикл

POST /generate
       ↓
   ┌────────┐    воркер берёт задачу из очереди
   │ pending│ ────────────────────────────────┐
   └────────┘                                 ▼
                                       ┌──────────────┐
                                       │  processing  │
                                       └──────────────┘
                                              ↓
              ┌──────────────┐ ←─── провайдер вернул результат
              │   completed  │
              └──────────────┘
                              ↘
                       ┌──────────────┐
                       │    failed    │ ←─── провайдер вернул ошибку, рефанд на ключ
                       └──────────────┘

Статус	Что это значит
`pending`	Задача создана, лежит в очереди RabbitMQ. Воркер ещё не взял её в работу.
`processing`	Воркер взял задачу, делает запрос в провайдера (Veo, Kling, и т.д.) и ждёт результата.
`completed`	Провайдер вернул результат — он в `result`. URL-ы файлов в S3 живут постоянно.
`failed`	Провайдер вернул ошибку или превышены ретраи. Сумма списания возвращена на ключ. `error` содержит человекочитаемое описание.

Получение результата

Вариант 1: Polling

Простейший подход — опрашивать GET /tasks/{task_id} периодически.

import time, requests

while True:
    r = requests.get(
        f"https://nexusapi.dev/tasks/{task_id}",
        headers={"Authorization": f"Bearer {KEY}"},
    ).json()
    if r["status"] in ("completed", "failed"):
        break
    time.sleep(3)

Вариант 2: Webhook (рекомендуется)

Передай webhook_url в params — мы сами POST’нем туда, когда задача завершится. Никакого polling’а, никакой нагрузки на твой ключ rate-limit’ом.

Подробнее — на странице Webhooks.

Структура ответа

GET /tasks/{task_id} возвращает:

{
  "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:56Z"
}

При failed:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "result": null,
  "error": "Provider rejected prompt: contains restricted content",
  "created_at": "2026-05-30T12:34:56Z"
}

Содержимое result зависит от модели — у видео там video_url, у изображений image_url/images. Конкретный формат для каждой модели смотри в каталоге.

Идемпотентность

Каждый POST /generate поддерживает заголовок Idempotency-Key. Если твой backend ретраит запрос (например, при таймауте) с тем же ключом — сервер вернёт тот же task_id, без создания второй задачи и без второго списания. TTL 24 часа.

Официальные SDK (Python и Node) генерируют ключ автоматически — ничего настраивать не нужно. Для ручных HTTP-запросов передай свой UUID:

POST /generate
Authorization: Bearer <NEXUS_KEY>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Подробнее — на странице Идемпотентность.

Сколько ждать

Ориентировочное время выполнения от создания до completed:

Тип задачи	Типичное время
Изображение (Nano-Banana, GPT-Image)	10-30 секунд
Изображение (Nano Banana, GPT Image 2, Seedream 5)	10-90 секунд
Видео 5-8с (Veo fast, Kling fast)	1-3 минуты
Видео 8с+ (Veo quality, Kling pro)	3-8 минут
Видео extend (Veo-extend)	10-15 минут

Это типичные значения. В пиковую нагрузку время может увеличиться; проверяй фактический статус по task_id или через webhook.