מדריכים

משימות אסינכרוניות

שלחו עבודות ארוכות טווח, בדקו סטטוס משימה, טפלו במצבים סופיים ואחזרו תוצאות.

חלק מהפעולות של Felo מחזירות task_id באופן מיידי ומסתיימות ברקע. הדפוס זהה בכל מקום: שליחה, בדיקה חוזרת ואז אחזור התוצאה.

שתי משפחות משימות

משפחה	שליחה	בדיקה חוזרת
תהליכי Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
יצירת מודלים	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /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.

מחזור חיים

שליחה. שלחו את פרמטרי המודל או התהליך. שליחה מוצלחת מחזירה task_id וסטטוס ראשוני.
בדיקה חוזרת. קראו את נקודת הקצה של המשימה במרווח קבוע. שמרו בקוד שלכם את המרווח ואת זמן ההמתנה המרבי.
סיום. בהצלחה, קראו את כתובות ה-URL של התוצאה או את שדות הפלט. בכשל, קראו את השגיאה והחליטו אם לשלוח מחדש.

ערכי סטטוס

משימות תהליך של Felo משתמשות בערכים באותיות גדולות:

סטטוס	משמעות
`RUNNING`	עדיין בעיבוד
`COMPLETED`	הסתיים בהצלחה
`FAILED`	כשל סופי; קראו `error_message`
`PENDING`	סופי בתגובה ההיסטורית; קראו `error_message`
`EXPIRED`	סופי; המשימה אינה זמינה יותר
`CANCELED`	סופי; המשימה בוטלה

משימות יצירת מודלים משתמשות בערכים באותיות קטנות: queued, running, succeeded, failed ו-interrupted. משימה שנכשלה עשויה לכלול אובייקט error עם message ו-type.

ערכי סטטוס לא מוכרים יכולים להופיע כשה-backend מתפתח. התייחסו לערך לא מוכר כלא סופי אלא אם התיעוד אומר אחרת.

בדיקה חוזרת

משימות תהליך של 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");
}

אחזור תוצאות

משימה	תוצאה
PPT	`GET /v2/tasks/{task_id}/historical` מחזיר `ppt_url`, `ppt_biz_id` ו-`live_doc_url` כשהם זמינים
דף נחיתה	התגובה ההיסטורית מחזירה את פלט העמוד ואת `live_doc_url` כשהם זמינים
וידאו / תמונה	תגובת הבדיקה מחזירה `outputs`; כשהמשימה הצליחה, הפריטים הם כתובות מדיה חתומות שאפשר להוריד באופן אנונימי. ראו יצירת תמונות לפרטי התפוגה וההורדה
ייצוא PPTX	תגובת הבדיקה מחזירה `download_url` ו-`expires_at` רק כאשר `status` הוא `COMPLETED`

כתובת ההורדה החתומה של PPTX פגה 30 דקות לאחר הנפקתה. קראו שוב ל-endpoint של GET כדי לקבל כתובת חדשה; הפעולה אינה מייצרת מחדש את הקובץ.

טיפול בכשלים

קראו את שדה השגיאה של המשימה לפני ניסיון חוזר. חלק מהכשלים נגרמים מהבקשה ויחזרו על עצמם.
אל תשלחו מחדש באופן עיוור בכל פסק זמן; בדקו תחילה אם המשימה עדיין RUNNING.
402 פירושו קרדיטים לא מספיקים. 429 פירושו מגבלת קצב. נסו שוב רק לאחר שהתנאי נפתר.
שדות callback ביצירת וידאו ותמונות מתעלמים מהם כעת. בדקו את נקודת הקצה של המשימה במקום להמתין ל-webhook.