Attività asincrone

Alcune operazioni Felo restituiscono subito un task_id e terminano in background. Lo schema è lo stesso ovunque: invia, interroga, poi recupera il risultato.

Due famiglie di attività

L'export PPTX è un'operazione asincrona separata: POST /v2/ppts/{ppt_business_id}/export, poi GET /v2/ppts/{ppt_business_id}/export.

SuperAgent non è un'API di polling. Restituisce una stream_key e usa SSE; vedi il riferimento SuperAgent.

Ciclo di vita

1. Invia. Invia i parametri del modello o del workflow. Un invio riuscito restituisce task_id e uno stato iniziale.
2. Interroga. Leggi l'endpoint dell'attività a intervalli regolari. Mantieni nel codice l'intervallo e un tempo massimo di attesa.
3. Concludi. In caso di successo, leggi gli URL dei risultati o i campi di output. In caso di errore, leggi l'errore e decidi se inviare di nuovo.

Valori di stato

Le attività dei workflow Felo usano valori in maiuscolo:

Le attività di generazione dei modelli usano valori in minuscolo: queued, running, succeeded, failed e interrupted. Un'attività non riuscita può includere un oggetto error con message e type.

Con l'evoluzione del backend possono comparire valori di stato sconosciuti. Tratta un valore sconosciuto come non terminale, salvo diversa indicazione nella documentazione.

Polling

• Attività dei workflow Felo: interroga ogni 2–5 secondi.
• Generazione di video: interroga ogni 5–10 secondi.
• Generazione di immagini: parti da 2–5 secondi e aumenta l'intervallo per le attività lunghe.
• Fermati su uno stato terminale, al timeout che hai scelto o dopo un numero massimo di tentativi.
• Aggiungi jitter quando molti client interrogano contemporaneamente.

Un semplice ciclo in 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");
}

Recuperare i risultati

L'URL di download firmato del PPTX scade 30 minuti dopo l'emissione. Chiama di nuovo l'endpoint GET per ottenere un URL aggiornato; questo non rigenera il file.

Gestione degli errori

• Leggi il campo di errore dell'attività prima di riprovare. Alcuni errori dipendono dalla richiesta e si ripeteranno.
• Non inviare di nuovo alla cieca a ogni timeout; controlla prima se l'attività è ancora RUNNING.
• 402 significa crediti insufficienti. 429 significa rate limit. Riprova solo dopo che la condizione è risolta.
• I campi di callback nella generazione di video e immagini al momento sono ignorati. Interroga l'endpoint dell'attività invece di attendere un webhook.

Correlati

• PPT Task API
• Landing Page Task API
• Riferimento Model API
• Generazione di immagini
• Errori, limiti e retry