Tareas asíncronas

Algunas operaciones de Felo devuelven un task_id inmediatamente y terminan en segundo plano. El patrón es el mismo en todas partes: enviar, consultar el estado y recuperar el resultado.

Dos familias de tareas

La exportación de PPTX es una operación asíncrona independiente: POST /v2/ppts/{ppt_business_id}/export y después GET /v2/ppts/{ppt_business_id}/export.

SuperAgent no es una API de consulta periódica. Devuelve un stream_key y usa SSE; consulta la referencia de SuperAgent.

Ciclo de vida

1. Enviar. Envía los parámetros del modelo o del flujo de trabajo. Un envío correcto devuelve task_id y un estado inicial.
2. Consultar. Lee el endpoint de la tarea a intervalos. Mantén el intervalo y un tiempo máximo de espera en tu código.
3. Finalizar. En caso de éxito, lee las URL de resultado o los campos de salida. En caso de fallo, lee el error y decide si volver a enviar.

Valores de estado

Las tareas de los flujos de trabajo de Felo usan valores en mayúsculas:

Las tareas de generación de modelos usan valores en minúsculas: queued, running, succeeded, failed e interrupted. Una tarea fallida puede incluir un objeto error con message y type.

Pueden aparecer valores de estado desconocidos a medida que evoluciona el backend. Trata un valor desconocido como no terminal salvo que la documentación indique lo contrario.

Consulta periódica

• Tareas de flujos de trabajo de Felo: consulta cada 2–5 segundos.
• Generación de video: consulta cada 5–10 segundos.
• Generación de imágenes: empieza con 2–5 segundos y aumenta el intervalo en tareas de larga duración.
• Detente en un estado terminal, en un tiempo de espera que elijas o tras un número máximo de intentos.
• Añade jitter cuando muchos clientes consulten a la vez.

Un bucle sencillo en 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");
}

Recuperar resultados

La URL de descarga firmada de PPTX caduca 30 minutos después de su emisión. Vuelve a llamar al endpoint GET para obtener una URL nueva; esto no regenera el archivo.

Gestión de fallos

• Lee el campo de error de la tarea antes de reintentar. Algunos fallos se deben a la solicitud y se repetirán.
• No vuelvas a enviar la tarea a ciegas en cada tiempo de espera; comprueba primero si la tarea sigue en estado RUNNING.
• 402 significa créditos insuficientes. 429 significa límite de solicitudes. Reintenta solo después de resolver la condición.
• Actualmente se ignoran los campos de devolución de llamada de la generación de video e imagen. Consulta el endpoint de la tarea en lugar de esperar un webhook.

Relacionado

• PPT Task API
• Landing Page Task API
• Referencia de la Model API
• Generación de imágenes
• Errores, límites y reintentos