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在 historical 响应中为终态；读取 error_message
EXPIRED终态；任务已不可用
CANCELED终态；任务已取消

模型生成任务使用小写值：queued、running、succeeded、failed 和 interrupted。失败任务可能包含带 message 和 type 的 error 对象。

未知状态值可能随后端演进出现。除非文档另有说明，否则将未知值视为非终态。

轮询

  • Felo 工作流任务：每 2–5 秒轮询一次。
  • 视频生成：每 5–10 秒轮询一次。
  • 图片生成：从 2–5 秒开始，长任务逐步退避。
  • 遇到终态、你设置的超时，或达到最大尝试次数时停止。
  • 多个客户端同时轮询时加入抖动。

一个简单的 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
落地页historical 响应在可用时返回页面输出和 live_doc_url
视频 / 图片轮询响应返回 outputs；成功时条目是可匿名下载的签名媒体 URL
PPTX 导出仅当 status 为 COMPLETED 时，轮询响应返回 download_url 和 expires_at

PPTX 签名下载 URL 在签发后 30 分钟过期。再次调用 GET endpoint 可获得新 URL；这不会重新生成文件。

失败处理

  • 重试前先读取任务的错误字段。有些失败由请求本身导致，会重复出现。
  • 不要每次超时都盲目重新提交；先确认任务是否仍为 RUNNING。
  • 402 表示服务额度不足。429 表示触发限流。只有条件解除后才重试。
  • 视频和图片生成的 callback 字段目前会被忽略。请轮询任务 endpoint，不要等待 webhook。

相关