गाइड

असिंक्रोनस टास्क

लंबे टास्क सबमिट करें, स्थिति पोल करें, अंतिम स्थितियां संभालें और नतीजे पाएं।

कुछ 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 export एक अलग असिंक्रोनस संचालन है: 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 वर्कफ़्लो कार्य uppercase मान उपयोग करते हैं:

स्थिति	अर्थ
`RUNNING`	अभी प्रोसेस हो रहा है
`COMPLETED`	सफलतापूर्वक पूरा हुआ
`FAILED`	टर्मिनल विफलता; `error_message` पढ़ें
`PENDING`	ऐतिहासिक प्रतिक्रिया में टर्मिनल; `error_message` पढ़ें
`EXPIRED`	टर्मिनल; कार्य अब उपलब्ध नहीं है
`CANCELED`	टर्मिनल; कार्य रद्द किया गया था

मॉडल जनरेशन कार्य lowercase मान उपयोग करते हैं: queued, running, succeeded, failed और interrupted। विफल कार्य में message और type वाला error ऑब्जेक्ट शामिल हो सकता है।

backend के विकसित होने के साथ अज्ञात स्थिति मान दिख सकते हैं। जब तक दस्तावेज़ अन्यथा न कहें, अज्ञात मान को गैर-टर्मिनल मानें।

पोलिंग

Felo वर्कफ़्लो कार्य: हर 2–5 सेकंड में पोल करें।
वीडियो जनरेशन: हर 5–10 सेकंड में पोल करें।
इमेज जनरेशन: 2–5 सेकंड से शुरू करें और लंबे समय तक चलने वाले कार्यों के लिए अंतराल बढ़ाएं।
टर्मिनल स्थिति पर, अपने चुने हुए timeout पर या अधिकतम प्रयास संख्या के बाद रुकें।
जब कई क्लाइंट एक साथ पोल करें तो 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 export	पोल प्रतिक्रिया केवल तब `download_url` और `expires_at` लौटाती है जब `status` `COMPLETED` हो

PPTX साइन किया गया डाउनलोड URL जारी होने के 30 मिनट बाद समाप्त हो जाता है। नए URL के लिए GET endpoint दोबारा कॉल करें; इससे फ़ाइल दोबारा नहीं बनती।

विफलता को संभालना

दोबारा प्रयास करने से पहले कार्य का error फ़ील्ड पढ़ें। कुछ विफलताएं अनुरोध के कारण होती हैं और दोहराई जाएंगी।
हर timeout पर बिना सोचे दोबारा सबमिट न करें; पहले जांचें कि कार्य अब भी RUNNING है या नहीं।
402 का अर्थ है अपर्याप्त क्रेडिट। 429 का अर्थ है दर सीमा। स्थिति हल होने के बाद ही दोबारा प्रयास करें।
वीडियो और इमेज जनरेशन पर callback फ़ील्ड वर्तमान में अनदेखे जाते हैं। webhook की प्रतीक्षा के बजाय कार्य endpoint पोल करें।