Průvodci

Asynchronní úlohy

Zadávejte dlouho běžící úlohy, dotazujte se na stav, ošetřujte koncové stavy a přebírejte výsledky.

Některé operace Felo vrací okamžitě task_id a dokončují se na pozadí. Vzor je všude stejný: odešlete, dotazujte se a potom získejte výsledek.

Dvě rodiny úloh

Rodina	Odeslání	Dotazování
Workflow Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
Generování modelu	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /api/v1/videos/generations/{task_id}`, `GET /api/v1/images/generations/{task_id}`

Export PPTX je samostatná asynchronní operace: POST /v2/ppts/{ppt_business_id}/export, potom GET /v2/ppts/{ppt_business_id}/export.

SuperAgent není API pro dotazování. Vrací stream_key a používá SSE; viz Reference SuperAgent.

Životní cyklus

Odeslání. Odešlete parametry modelu nebo workflow. Úspěšné odeslání vrací task_id a počáteční stav.
Dotazování. Čtěte endpoint úlohy v určeném intervalu. Ve svém kódu udržujte interval a maximální dobu čekání.
Dokončení. Při úspěchu přečtěte URL výsledků nebo výstupní pole. Při selhání přečtěte chybu a rozhodněte, zda úlohu odeslat znovu.

Hodnoty stavu

Úlohy workflow Felo používají velká písmena:

Stav	Význam
`RUNNING`	Stále se zpracovává
`COMPLETED`	Úspěšně dokončeno
`FAILED`	Koncové selhání; přečtěte `error_message`
`PENDING`	Koncový stav v historické odpovědi; přečtěte `error_message`
`EXPIRED`	Koncový stav; úloha již není dostupná
`CANCELED`	Koncový stav; úloha byla zrušena

Úlohy generování modelu používají malá písmena: queued, running, succeeded, failed a interrupted. Neúspěšná úloha může obsahovat objekt error s poli message a type.

Neznámé hodnoty stavu se mohou objevit, jak se backend vyvíjí. S neznámou hodnotou zacházejte jako s nekoncovou, pokud dokumentace nestanoví jinak.

Dotazování

Úlohy workflow Felo: dotazujte se každých 2–5 sekund.
Generování videa: dotazujte se každých 5–10 sekund.
Generování obrázků: začněte na 2–5 sekundách a u dlouho běžících úloh zvyšujte interval.
Zastavte při koncovém stavu, při vámi zvoleném časovém limitu nebo po maximálním počtu pokusů.
Přidejte jitter, když se dotazuje mnoho klientů najednou.

Jednoduchá smyčka v 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");
}

Získání výsledků

Úloha	Výsledek
PPT	`GET /v2/tasks/{task_id}/historical` vrací `ppt_url`, `ppt_biz_id` a `live_doc_url`, pokud jsou dostupné
Landing page	Historická odpověď vrací výstup stránky a `live_doc_url`, pokud je dostupné
Video / obrázek	Odpověď při dotazování vrací `outputs`; při úspěchu jsou položkami podepsané mediální URL, které lze anonymně stáhnout. Podrobnosti o expiraci a stahování najdete v části Generování obrázků
Export PPTX	Odpověď při dotazování vrací `download_url` a `expires_at` pouze tehdy, když je `status` `COMPLETED`

Podepsaná URL pro stažení PPTX expiruje 30 minut po vydání. Zavolejte znovu endpoint GET pro novou URL; soubor se tím znovu nevygeneruje.

Řešení selhání

Před opakováním přečtěte pole chyby úlohy. Některá selhání způsobuje požadavek a budou se opakovat.
Neodesílejte slepě znovu při každém časovém limitu; nejprve zkontrolujte, zda úloha stále není RUNNING.
402 znamená nedostatek kreditů. 429 znamená limit rychlosti. Opakujte až po vyřešení podmínky.
Pole zpětných volání u generování videa a obrázků jsou aktuálně ignorována. Namísto čekání na webhook dotazujte endpoint úlohy.