Felo API PlatformFelo API Platform

指南

非同步任務

提交長任務、輪詢狀態、處理終態並取得結果。

部分 Felo 操作會立即回傳 task_id，並在背景完成。模式在各處都相同：提交、輪詢，然後取得結果。

兩種任務家族

家族提交輪詢
Felo 工作流程POST /v2/ppts、POST /v2/landing_page、POST /v2/mindmapGET /v2/tasks/{task_id}/status
模型生成POST /api/v1/videos/generations、POST /api/v1/images/generationsGET /api/v1/videos/generations/{task_id}、GET /api/v1/images/generations/{task_id}

PPTX 匯出是另一個非同步操作：POST /v2/ppts/{ppt_business_id}/export，然後 GET /v2/ppts/{ppt_business_id}/export。

SuperAgent 不是輪詢式 API。它回傳 stream_key 並使用 SSE；請參閱 SuperAgent 參考。

生命週期

  1. 提交。 送出模型或工作流程參數。提交成功會回傳 task_id 與初始狀態。
  2. 輪詢。 依固定間隔讀取任務 endpoint。在程式碼中保有間隔與最長等待時間。
  3. 完成。 成功時讀取結果 URL 或輸出欄位。失敗時讀取錯誤，判斷是否重新提交。

狀態值

Felo 工作流程任務使用大寫值：

狀態含義
RUNNING仍在處理
COMPLETED成功完成
FAILED終態失敗；讀取 error_message
PENDING在歷史回應中為終態；讀取 error_message
EXPIRED終態；任務已不再可用
CANCELED終態；任務已取消

模型生成任務使用小寫值：queued、running、succeeded、failed 與 interrupted。失敗的任務可能包含帶有 message 與 type 的 error 物件。

後端演進時可能出現未知狀態值。除非文件另有說明，否則把未知值視為非終態。

輪詢

  • Felo 工作流程任務：每 2–5 秒輪詢一次。
  • 影片生成：每 5–10 秒輪詢一次。
  • 圖像生成：從 2–5 秒開始，長時間任務逐步拉長間隔。
  • 在終態、你選擇的逾時時間，或達到最大嘗試次數時停止。
  • 許多用戶端同時輪詢時，加入 jitter。

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

取得結果

任務結果
PPTGET /v2/tasks/{task_id}/historical 會回傳 ppt_url、ppt_biz_id，以及在可用時回傳 live_doc_url
落地頁歷史回應會回傳頁面輸出，以及在可用時回傳 live_doc_url
影片 / 圖像輪詢回應會回傳 outputs；成功時，項目是可匿名下載的簽章媒體 URL
PPTX 匯出只有在 status 為 COMPLETED 時，輪詢回應才會回傳 download_url 與 expires_at

PPTX 簽名下載 URL 在簽發後 30 分鐘過期。再次呼叫 GET endpoint 取得新 URL；這不會重新生成檔案。

失敗處理

  • 重試前先讀取任務的錯誤欄位。有些失敗由請求本身造成，會重複發生。
  • 不要每次逾時就盲目重新提交；先確認任務是否仍是 RUNNING。
  • 402 表示額度不足。429 表示觸發限流。條件解除後才重試。
  • 影片與圖像生成的 callback 欄位目前會被忽略。請輪詢任務 endpoint，不要等待 webhook。

相關