Tarefas assíncronas

Algumas operações da Felo retornam um task_id imediatamente e terminam em segundo plano. O padrão é o mesmo em todos os casos: enviar, consultar e depois obter o resultado.

Duas famílias de tarefas

A exportação de PPTX é uma operação assíncrona separada: POST /v2/ppts/{ppt_business_id}/export, depois GET /v2/ppts/{ppt_business_id}/export.

O SuperAgent não é uma API de consulta por polling. Ele retorna uma stream_key e usa SSE; consulte a referência do SuperAgent.

Ciclo de vida

1. Envie. Mande os parâmetros do modelo ou do fluxo. Um envio bem-sucedido retorna task_id e um status inicial.
2. Consulte. Leia o endpoint da tarefa em intervalos. Mantenha o intervalo e um tempo máximo de espera no seu código.
3. Finalize. Em caso de sucesso, leia as URLs de resultado ou os campos de saída. Em caso de falha, leia o erro e decida se deve reenviar.

Valores de status

As tarefas de fluxo Felo usam valores em maiúsculas:

As tarefas de geração de modelos usam valores em minúsculas: queued, running, succeeded, failed e interrupted. Uma tarefa com falha pode incluir um objeto error com message e type.

Valores de status desconhecidos podem aparecer conforme o backend evolui. Trate um valor desconhecido como não terminal, a menos que a documentação diga o contrário.

Consulta por polling

• Tarefas de fluxo Felo: consulte a cada 2–5 segundos.
• Geração de vídeo: consulte a cada 5–10 segundos.
• Geração de imagens: comece com 2–5 segundos e aumente o intervalo em tarefas demoradas.
• Pare em um status terminal, em um timeout que você escolher ou após um número máximo de tentativas.
• Adicione variação aleatória (jitter) quando muitos clientes consultam ao mesmo tempo.

Um loop simples em 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");
}

Obtenha os resultados

A URL assinada de download do PPTX expira 30 minutos após a emissão. Chame o endpoint GET novamente para obter uma URL nova; isso não regenera o arquivo.

Tratamento de falhas

• Leia o campo de erro da tarefa antes de tentar novamente. Algumas falhas são causadas pela própria requisição e vão se repetir.
• Não reenvie às cegas a cada timeout; primeiro verifique se a tarefa ainda está RUNNING.
• 402 significa créditos insuficientes. 429 significa limite de requisições. Tente novamente apenas depois que a condição for resolvida.
• Campos de callback em geração de vídeo e de imagem são ignorados no momento. Consulte o endpoint da tarefa em vez de esperar por um webhook.

Relacionados

• PPT Task API
• Landing Page Task API
• Referência da Model API
• Geração de imagens
• Erros, limites e novas tentativas