Felo API PlatformFelo API Platform

Руководства

Асинхронные задачи

Отправляйте длительные задачи, опрашивайте статус и обрабатывайте терминальные состояния, чтобы забрать результат.

Некоторые операции Felo сразу возвращают task_id и завершаются в фоне. Схема везде одна: отправить, опросить, получить результат.

Две группы задач

ГруппаОтправкаОпрос
Рабочие процессы FeloPOST /v2/ppts, POST /v2/landing_page, POST /v2/mindmapGET /v2/tasks/{task_id}/status
Генерация моделямиPOST /api/v1/videos/generations, POST /api/v1/images/generationsGET /api/v1/videos/generations/{task_id}, GET /api/v1/images/generations/{task_id}

Экспорт PPTX — отдельная асинхронная операция: POST /v2/ppts/{ppt_business_id}/export, затем GET /v2/ppts/{ppt_business_id}/export.

SuperAgent не является polling API. Он возвращает stream_key и использует SSE; см. SuperAgent reference.

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

  1. Отправка. Передайте параметры модели или рабочего процесса. Успешная отправка возвращает task_id и начальный статус.
  2. Опрос. Читайте endpoint задачи с интервалом. Храните интервал и максимальное время ожидания в коде.
  3. Завершение. При успехе прочитайте URL результатов или выходные поля. При ошибке прочитайте сообщение и решите, отправлять ли заново.

Значения статуса

Задачи рабочих процессов Felo используют значения в верхнем регистре:

СтатусЗначение
RUNNINGЕщё обрабатывается
COMPLETEDУспешно завершено
FAILEDТерминальная ошибка; прочитайте error_message
PENDINGВ историческом ответе терминальный; прочитайте error_message
EXPIREDТерминальный; задача больше недоступна
CANCELEDТерминальный; задача отменена

Задачи генерации моделями используют значения в нижнем регистре: queued, running, succeeded, failed и interrupted. Неудачная задача может содержать объект error с полями message и type.

По мере развития бэкенда могут появляться неизвестные статусы. Считайте неизвестное значение нетерминальным, если документация не говорит иначе.

Опрос

  • Задачи рабочих процессов Felo: каждые 2–5 секунд.
  • Генерация видео: каждые 5–10 секунд.
  • Генерация изображений: начните с 2–5 секунд и увеличивайте интервал для долгих задач.
  • Останавливайтесь на терминальном статусе, по выбранному таймауту или после максимального числа попыток.
  • Добавляйте jitter, когда одновременно опрашивают многие клиенты.

Простой цикл на Node.js:

async function pollStatus(taskId, { timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await fetch(`https://openapi.felo.ai/v2/tasks/${taskId}/status`, {
      headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}` },
    });
    if (!response.ok) throw new Error(`status ${response.status}`);
    const payload = await response.json();
    const status = payload.data?.status;
    if (status === "COMPLETED") return payload.data;
    if (["FAILED", "PENDING", "EXPIRED", "CANCELED"].includes(status)) {
      throw new Error(payload.data?.error_message || status);
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  throw new Error("task timed out");
}

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

ЗадачаРезультат
PPTGET /v2/tasks/{task_id}/historical возвращает ppt_url, ppt_biz_id и live_doc_url, если он доступен
Landing pageИсторический ответ возвращает результат страницы и live_doc_url, если он доступен
Видео / изображениеОтвет опроса возвращает outputs; при успехе элементы — это подписанные URL медиа, доступные для анонимного скачивания
Экспорт PPTXОтвет опроса возвращает download_url и expires_at только когда status равен COMPLETED

Подписанный URL скачивания PPTX истекает через 30 минут после выдачи. Вызовите GET endpoint снова, чтобы получить новый URL; файл при этом не пересоздаётся.

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

  • Прочитайте поле ошибки задачи перед повторной попыткой. Некоторые ошибки вызваны самим запросом и повторятся.
  • Не отправляйте задачу заново при каждом таймауте; сначала проверьте, не в статусе ли она ещё RUNNING.
  • 402 означает нехватку кредитов. 429 — превышение лимита. Повторяйте только после устранения причины.
  • Поля callback при генерации видео и изображений сейчас игнорируются. Опрашивайте endpoint задачи, а не ждите webhook.

Связанные разделы