Asynchrone taken

Sommige Felo-bewerkingen retourneren direct een task_id en ronden op de achtergrond af. Het patroon is overal hetzelfde: indienen, pollen en daarna het resultaat ophalen.

Twee soorten taken

PPTX-export is een aparte asynchrone bewerking: POST /v2/ppts/{ppt_business_id}/export, daarna GET /v2/ppts/{ppt_business_id}/export.

SuperAgent is geen polling-API. De API retourneert een stream_key en gebruikt SSE; zie de SuperAgent-referentie.

Levenscyclus

1. Indienen. Verstuur de parameters van het model of de workflow. Een geslaagde indiening retourneert een task_id en een eerste status.
2. Pollen. Lees het taak-endpoint met een vaste tussenpoos. Neem de tussenpoos en een maximale wachttijd op in je code.
3. Afronden. Lees bij succes de resultaat-URL's of uitvoervelden. Lees bij een fout de foutmelding en beslis of je opnieuw wilt indienen.

Statuswaarden

Felo-workflowtaken gebruiken waarden in hoofdletters:

Taken voor modelgeneratie gebruiken waarden in kleine letters: queued, running, succeeded, failed en interrupted. Een mislukte taak kan een error-object met message en type bevatten.

Onbekende statuswaarden kunnen opduiken naarmate de backend zich ontwikkelt. Behandel een onbekende waarde als niet-definitief, tenzij de documentatie anders zegt.

Polling

• Felo-workflowtaken: poll elke 2–5 seconden.
• Videogeneratie: poll elke 5–10 seconden.
• Beeldgeneratie: begin met 2–5 seconden en verhoog de tussenpoos bij langdurige taken.
• Stop bij een definitieve status, bij een time-out die je zelf kiest of na een maximumaantal pogingen.
• Voeg jitter toe wanneer veel clients tegelijk pollen.

Een eenvoudige Node.js-lus:

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");
}

Resultaten ophalen

De ondertekende download-URL voor PPTX verloopt 30 minuten na afgifte. Roep het GET-endpoint opnieuw aan voor een nieuwe URL; het bestand wordt daarbij niet opnieuw gegenereerd.

Omgaan met fouten

• Lees het foutveld van de taak voordat je het opnieuw probeert. Sommige fouten worden door het verzoek veroorzaakt en zullen zich herhalen.
• Dien niet blind opnieuw in bij elke time-out; controleer eerst of de taak nog RUNNING is.
• 402 betekent onvoldoende service-tegoed. 429 betekent een rate limit. Probeer het pas opnieuw als de oorzaak is opgelost.
• Callbackvelden bij video- en beeldgeneratie worden momenteel genegeerd. Poll het taak-endpoint in plaats van op een webhook te wachten.

Gerelateerd

• PPT Task API
• Landing Page Task API
• Model API-referentie
• Beeldgeneratie
• Fouten, limieten en nieuwe pogingen