Tâches asynchrones

Certaines opérations Felo renvoient immédiatement un task_id et se terminent en arrière-plan. Le schéma est le même partout : soumettre, interroger, puis récupérer le résultat.

Deux familles de tâches

L'export PPTX est une opération asynchrone distincte : POST /v2/ppts/{ppt_business_id}/export, puis GET /v2/ppts/{ppt_business_id}/export.

SuperAgent n'est pas une API d'interrogation. Il renvoie un stream_key et utilise SSE ; consultez la référence SuperAgent.

Cycle de vie

1. Soumettre. Envoyez les paramètres du modèle ou du workflow. Une soumission réussie renvoie task_id et un statut initial.
2. Interroger. Lisez l'endpoint de la tâche à intervalles réguliers. Conservez l'intervalle et un délai d'attente maximal dans votre code.
3. Terminer. En cas de succès, lisez les URL de résultat ou les champs de sortie. En cas d'échec, lisez l'erreur et décidez s'il faut soumettre à nouveau.

Valeurs de statut

Les tâches de workflow Felo utilisent des valeurs en majuscules :

Les tâches de génération par modèle utilisent des valeurs en minuscules : queued, running, succeeded, failed et interrupted. Une tâche échouée peut inclure un objet error avec message et type.

Des valeurs de statut inconnues peuvent apparaître à mesure que le backend évolue. Traitez une valeur inconnue comme non terminale, sauf indication contraire dans la documentation.

Interrogation

• Tâches de workflow Felo : interrogez toutes les 2 à 5 secondes.
• Génération vidéo : interrogez toutes les 5 à 10 secondes.
• Génération d'images : commencez par 2 à 5 secondes et espacez les tentatives pour les tâches longues.
• Arrêtez-vous sur un statut terminal, sur un délai d'attente que vous avez choisi ou après un nombre maximal de tentatives.
• Ajoutez un jitter lorsque de nombreux clients interrogent en même temps.

Une boucle Node.js simple :

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

Récupérer les résultats

L'URL de téléchargement signée PPTX expire 30 minutes après son émission. Appelez à nouveau l'endpoint GET pour obtenir une URL fraîche ; cela ne régénère pas le fichier.

Gestion des échecs

• Lisez le champ d'erreur de la tâche avant de réessayer. Certains échecs sont causés par la requête et se répéteront.
• Ne soumettez pas à nouveau aveuglément à chaque expiration de délai ; vérifiez d'abord si la tâche est toujours RUNNING.
• 402 signifie des crédits insuffisants. 429 signifie une limite de débit. Ne réessayez qu'une fois la condition résolue.
• Les champs de callback des générations vidéo et image sont actuellement ignorés. Interrogez l'endpoint de la tâche au lieu d'attendre un webhook.

Voir aussi

• PPT Task API
• Landing Page Task API
• Référence du Model API
• Génération d'images
• Erreurs, limites et nouvelles tentatives