رہنما

غیر متزامن کام

طویل المدتی کام جمع کریں، کام کی حالت معلوم کریں، آخری حالتوں کو سنبھالیں اور نتائج حاصل کریں۔

کچھ 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 ایکسپورٹ ایک الگ async آپریشن ہے: POST /v2/ppts/{ppt_business_id}/export، پھر GET /v2/ppts/{ppt_business_id}/export۔

SuperAgent پولنگ API نہیں ہے۔ یہ ایک stream_key واپس کرتا ہے اور SSE استعمال کرتا ہے؛ SuperAgent ریفرنس دیکھیں۔

لائف سائیکل

جمع کرائیں۔ ماڈل یا ورک فلو کے پیرامیٹرز بھیجیں۔ کامیاب جمع کرانے پر task_id اور ابتدائی حالت ملتی ہے۔
پول کریں۔ وقفے سے ٹاسک endpoint پڑھیں۔ وقفہ اور زیادہ سے زیادہ انتظار کا وقت اپنے کوڈ میں رکھیں۔
مکمل کریں۔ کامیابی پر نتیجے کے URLs یا آؤٹ پٹ فیلڈز پڑھیں۔ ناکامی پر ایرر پڑھیں اور فیصلہ کریں کہ دوبارہ جمع کرانا ہے یا نہیں۔

اسٹیٹس ویلیوز

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");
}

نتائج حاصل کریں

ٹاسک	نتیجہ
PPT	`GET /v2/tasks/{task_id}/historical` دستیاب ہونے پر `ppt_url`، `ppt_biz_id` اور `live_doc_url` واپس کرتا ہے
لینڈنگ پیج	تاریخی جواب دستیاب ہونے پر صفحے کا آؤٹ پٹ اور `live_doc_url` واپس کرتا ہے
ویڈیو / تصویر	پول جواب `outputs` واپس کرتا ہے؛ کامیابی پر اندراجات دستخط شدہ میڈیا URLs ہوتے ہیں جنہیں گمنام طور پر ڈاؤن لوڈ کیا جا سکتا ہے۔ میعاد ختم ہونے اور ڈاؤن لوڈ کی تفصیلات کے لیے تصویر جنریشن دیکھیں
PPTX ایکسپورٹ	پول جواب `download_url` اور `expires_at` صرف اُس وقت واپس کرتا ہے جب `status` `COMPLETED` ہو

PPTX کا دستخط شدہ ڈاؤن لوڈ URL جاری ہونے کے 30 منٹ بعد میعاد ختم ہو جاتا ہے۔ تازہ URL کے لیے GET endpoint دوبارہ کال کریں؛ اِس سے فائل دوبارہ نہیں بنتی۔

ناکامی سے نمٹنا

دوبارہ کوشش سے پہلے ٹاسک کا ایرر فیلڈ پڑھیں۔ کچھ ناکامیاں درخواست کی وجہ سے ہوتی ہیں اور دہرائی جائیں گی۔
ہر ٹائم آؤٹ پر اندھا دھند دوبارہ جمع نہ کریں؛ پہلے چیک کریں کہ ٹاسک اب بھی RUNNING ہے یا نہیں۔
402 کا مطلب ناکافی کریڈٹ ہے۔ 429 کا مطلب ریٹ کی حد ہے۔ دوبارہ کوشش صرف حالت حل ہونے کے بعد کریں۔
ویڈیو اور تصویر جنریشن کے callback فیلڈز فی الحال نظر انداز کیے جاتے ہیں۔ webhook کا انتظار کرنے کے بجائے ٹاسک endpoint پول کریں۔