راهنماها

کارهای ناهمزمان

کارهای طولانی‌مدت را ارسال کنید، وضعیت کار را بررسی کنید، حالت‌های پایانی را مدیریت کنید و نتایج را دریافت کنید.

برخی عملیات 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 و یک وضعیت آغازین برمی‌گرداند.
پیگیری وضعیت. endpoint وظیفه را با فاصله زمانی بخوانید. فاصله و بیشینه زمان انتظار را در کد خود نگه دارید.
پایان. در موفقیت، URLهای نتیجه یا فیلدهای خروجی را بخوانید. در شکست، خطا را بخوانید و تصمیم بگیرید دوباره ارسال کنید یا نه.

مقدارهای وضعیت

وظایف گردش‌کار Felo از مقدارهای حروف بزرگ استفاده می‌کنند:

وضعیت	معنا
`RUNNING`	همچنان در حال پردازش
`COMPLETED`	با موفقیت تمام شد
`FAILED`	شکست پایانی؛ `error_message` را بخوانید
`PENDING`	پایانی در پاسخ تاریخی؛ `error_message` را بخوانید
`EXPIRED`	پایانی؛ وظیفه دیگر در دسترس نیست
`CANCELED`	پایانی؛ وظیفه لغو شد

وظایف تولید مدل از مقدارهای حروف کوچک استفاده می‌کنند: queued، running، succeeded، failed و interrupted. وظیفه ناموفق ممکن است یک شیء error با message و type داشته باشد.

مقدارهای وضعیت ناشناخته ممکن است با تحول بک‌اند ظاهر شوند. تا وقتی مستندات خلافش را نگفته، مقدار ناشناخته را غیرپایانی بدانید.

پیگیری وضعیت

وظایف گردش‌کار 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` را برمی‌گرداند؛ در موفقیت، مدخل‌ها URLهای رسانه امضاشده‌ای هستند که می‌توان بی‌نام دانلود کرد. برای جزئیات انقضا و دانلود تولید تصویر را ببینید
خروجی PPTX	پاسخ پیگیری وضعیت فقط وقتی `status` برابر `COMPLETED` است `download_url` و `expires_at` را برمی‌گرداند

URL امضاشده دانلود PPTX، 30 دقیقه پس از صدور منقضی می‌شود. برای URL تازه دوباره endpoint GET را صدا بزنید؛ این کار فایل را دوباره تولید نمی‌کند.

مدیریت شکست

پیش از تلاش دوباره، فیلد خطای وظیفه را بخوانید. برخی شکست‌ها ناشی از درخواست‌اند و تکرار می‌شوند.
در هر مهلت به‌صورت کورکورانه دوباره ارسال نکنید؛ نخست بررسی کنید وظیفه هنوز RUNNING است یا نه.
402 یعنی اعتبار ناکافی. 429 یعنی محدودیت نرخ. فقط پس از رفع شرط دوباره تلاش کنید.
فیلدهای callback در تولید ویدیو و تصویر در حال حاضر نادیده گرفته می‌شوند. به‌جای انتظار برای webhook، endpoint وظیفه را پیگیری کنید.