Посібники

Асинхронні завдання

Надсилайте тривалі завдання, опитуйте статус, обробляйте кінцеві стани й отримуйте результати.

Деякі операції Felo одразу повертають task_id і завершуються у фоновому режимі. Схема всюди однакова: надіслати, опитати, потім отримати результат.

Дві родини завдань

Родина	Надсилання	Опитування
Робочі процеси Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
Генерація моделлю	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /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 — це не API опитування. Він повертає stream_key і використовує SSE; див. Довідник SuperAgent.

Життєвий цикл

Надішліть. Передайте параметри моделі або робочого процесу. Успішне надсилання повертає task_id і початковий статус.
Опитуйте. Читайте endpoint завдання з певним інтервалом. Задайте в коді інтервал і максимальний час очікування.
Завершіть. У разі успіху прочитайте 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 секунд і збільшуйте інтервал для тривалих завдань.
Зупиняйтеся на термінальному статусі, на вибраному вами тайм-ауті або після максимальної кількості спроб.
Додавайте випадковий розкид, коли багато клієнтів опитують одночасно.

Простий цикл на 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");
}

Отримання результатів

Завдання	Результат
PPT	`GET /v2/tasks/{task_id}/historical` повертає `ppt_url`, `ppt_biz_id` і `live_doc_url`, коли вони доступні
Цільова сторінка	Історична відповідь повертає вивід сторінки та `live_doc_url`, коли вони доступні
Відео / зображення	Відповідь на опитування повертає `outputs`; у разі успіху записи є підписаними URL-адресами медіа, які можна завантажити анонімно. Про строк дії та завантаження див. Генерація зображень
Експорт PPTX	Відповідь на опитування повертає `download_url` і `expires_at`, лише коли `status` дорівнює `COMPLETED`

Підписана URL-адреса для завантаження PPTX діє 30 хвилин після видачі. Викличте endpoint GET знову, щоб отримати свіжу URL-адресу; це не перегенеровує файл.

Обробка збоїв

Прочитайте поле помилки завдання перед повторною спробою. Деякі збої спричинені запитом і повторяться.
Не надсилайте повторно навмання після кожного тайм-ауту; спершу перевірте, чи завдання досі в статусі RUNNING.
402 означає недостатньо кредитів. 429 означає обмеження швидкості. Повторіть спробу лише після усунення умови.
Поля зворотного виклику для генерації відео та зображень наразі ігноруються. Опитуйте endpoint завдання замість очікування webhook.