Felo API PlatformFelo API Platform

ガイド

非同期タスク

長時間のタスクを送信し、ステータスをポーリングし、終端状態を処理して結果を取得します。

一部の Felo 操作はすぐに task_id を返し、バックグラウンドで完了します。パターンはどこでも同じです。送信し、ポーリングし、結果を取得します。

2 種類のタスク

種類送信ポーリング
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 referenceを参照してください。

ライフサイクル

  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 を返します
Landing page履歴レスポンスがページ出力と、利用可能な場合は live_doc_url を返します
動画 / 画像ポーリングレスポンスが outputs を返します。成功時、各項目は匿名でダウンロードできる署名付きメディア URL です
PPTX エクスポートポーリングレスポンスは status が COMPLETED のときだけ download_url と expires_at を返します

PPTX の署名付きダウンロード URL は発行から 30 分で失効します。GET endpoint をもう一度呼んで新しい URL を取得してください。ファイルが再生成されるわけではありません。

失敗時の扱い

  • 再試行する前にタスクのエラーフィールドを読みます。リクエスト自体に原因がある失敗は繰り返します。
  • タイムアウトのたびに無条件で再送信しないでください。まずタスクがまだ RUNNING か確認します。
  • 402 はクレジット不足、429 はレート制限です。条件が解消してから再試行してください。
  • 動画・画像生成の callback フィールドは現在無視されます。webhook を待たず、タスク endpoint をポーリングしてください。

関連