গাইড

অ্যাসিঙ্ক্রোনাস টাস্ক

দীর্ঘ কাজ জমা দিন, স্ট্যাটাস পোল করুন, চূড়ান্ত অবস্থা সামলান এবং ফলাফল নিন।

কিছু 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 বা output ফিল্ড পড়ুন। ব্যর্থ হলে ত্রুটি পড়ুন এবং আবার সাবমিট করবেন কি না ঠিক করুন।

স্ট্যাটাস মান

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` ফেরত দেয়
Landing page	ঐতিহাসিক রেসপন্স উপলব্ধ হলে পেজ আউটপুট ও `live_doc_url` ফেরত দেয়
ভিডিও / ইমেজ	পোল রেসপন্স `outputs` ফেরত দেয়; সফল হলে এন্ট্রিগুলো স্বাক্ষরিত মিডিয়া URL যা বেনামে ডাউনলোড করা যায়। মেয়াদ ও ডাউনলোডের বিস্তারিত জানতে Image Generation দেখুন
PPTX এক্সপোর্ট	`status` `COMPLETED` হলে কেবল তখনই পোল রেসপন্স `download_url` ও `expires_at` ফেরত দেয়

PPTX স্বাক্ষরিত ডাউনলোড URL ইস্যু হওয়ার 30 মিনিট পরে মেয়াদোত্তীর্ণ হয়। নতুন URL-এর জন্য GET endpoint আবার কল করুন; এটি ফাইলটি পুনরায় জেনারেট করে না।

ব্যর্থতা সামলানো

রিট্রাই করার আগে টাস্কের error ফিল্ড পড়ুন। কিছু ব্যর্থতা অনুরোধের কারণে হয় এবং পুনরাবৃত্তি হবে।
প্রতিটি টাইমআউটে অন্ধভাবে আবার সাবমিট করবেন না; প্রথমে টাস্কটি এখনো RUNNING কি না দেখুন।
402 মানে অপর্যাপ্ত ক্রেডিট। 429 মানে রেট সীমা। পরিস্থিতি সমাধানের পরেই রিট্রাই করুন।
ভিডিও ও ইমেজ জেনারেশনের callback ফিল্ড বর্তমানে উপেক্ষা করা হয়। webhook-এর অপেক্ষার বদলে টাস্ক endpoint পোল করুন।