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

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)

Интервал polling'а

Для изображений достаточно 1-2 секунды, для видео — 3-5 секунд. Опрашивать чаще раза в секунду нет смысла — статус не обновится так быстро.

Вариант 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 создаёт новую задачу. Если твой backend ретраит запрос (например, при таймауте), может создаться дубль. Поддержка Idempotency-Key заголовка для предотвращения дублей — в ближайшем релизе.

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

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

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

Это типичные значения. В пиковую нагрузку или при сбое primary-провайдера и переключении на fallback время может увеличиться в 1.5-2 раза.