الأدلة

المهام غير المتزامنة

أرسل مهامًا طويلة التشغيل، واستعلم عن حالة المهمة، وتعامل مع الحالات النهائية، واسترجع النتائج.

تعيد بعض عمليات 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 ثوانٍ وتراجع تدريجيًا للمهام الطويلة.
توقف عند حالة نهائية، أو عند مهلة تختارها، أو بعد حد أقصى لعدد المحاولات.
أضف تشويشًا عشوائيًا عندما يستطلع عملاء كثيرون في الوقت نفسه.

حلقة 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	تعيد استجابة الاستطلاع `download_url` و`expires_at` فقط عندما تكون `status` هي `COMPLETED`

تنتهي صلاحية عنوان URL الموقّع لتنزيل PPTX بعد 30 دقيقة من إصداره. استدعِ endpoint GET مجددًا للحصول على عنوان جديد؛ وهذا لا يعيد توليد الملف.

معالجة الفشل

اقرأ حقل خطأ المهمة قبل إعادة المحاولة. بعض حالات الفشل يسببها الطلب وستتكرر.
لا تعد الإرسال عشوائيًا عند كل مهلة؛ تحقق أولًا مما إذا كانت المهمة لا تزال RUNNING.
تعني 402 أرصدة غير كافية. وتعني 429 حد معدل. أعد المحاولة فقط بعد حل الحالة.
تُتجاهل حاليًا حقول رد الاتصال في توليد الفيديو والصور. استطلع endpoint المهمة بدلًا من انتظار webhook.