PiAPI पोलिंग और Webhook: कार्य पूरा होने को भरोसेमंद तरीके से संभालें

चित्र या वीडियो अनुरोध स्वीकार होने के बाद भी पूर्णता प्रवाह चाहिए। PiAPI की एकीकृत API के कार्यों में ID सहेजें, अंतिम स्थिति जाँचें और फिर मॉडल के अनुसार आउटपुट संभालें। शुरुआती एकीकरण के लिए पोलिंग आसान है; Webhook से बैकएंड काम पूरा होते ही प्रतिक्रिया दे सकता है।

1. कार्य ID सहेजें और पोलिंग सीमित रखें

कार्य बनाने पर data.task_id को अपनी जॉब ID के साथ स्थायी रूप से सहेजें। सर्वर की API कुंजी से उसी कार्य को पढ़ें। सफल HTTP उत्तर से जनरेशन पूरा होना सिद्ध नहीं होता; data.status जाँचें।

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

completed पर मॉडल के अनुसार data.output सत्यापित करें; failed पर data.error दर्ज करें। प्रयास सीमित रखें, अंतराल बढ़ाएँ और यादृच्छिक विलंब जोड़ें। ऐप की प्रतीक्षा अवधि स्थानीय निर्णय है; उसका समाप्त होना दूरस्थ कार्य के विफल या रद्द होने का प्रमाण नहीं है। बाद में मिलान के लिए ID रखें।

2. प्रमाणित कॉलबैक जोड़ें

नीचे की कॉन्फ़िगरेशन को मान्य कार्य निर्माण अनुरोध में मिलाएँ और मौजूदा फ़ील्ड बनाए रखें। सार्वजनिक HTTPS एंडपॉइंट और बैकएंड के सुरक्षित भंडार का सीक्रेट इस्तेमाल करें। PiAPI दस्तावेज़ के अनुसार यह सीक्रेट x-webhook-secret हेडर में आता है; सूचना स्वीकार करने से पहले सत्यापित करें।

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

Webhook JSON में timestamp और data होते हैं। जाँचें कि कार्य आपके ऐप का है, फिर घटना को स्थायी रूप से दर्ज करें या स्थायी कतार में डालें और जल्दी 2xx उत्तर दें। डाउनलोड व लंबे काम HTTP हैंडलर के बाहर करें। दोहराव की अपेक्षा रखें: दस्तावेज़ सफल उत्तर न मिलने पर पुनः भेजने का वर्णन करते हैं।

3. पोलिंग और कॉलबैक को एक प्रक्रिया में लाएँ

दोनों के लिए एक पूर्णता हैंडलर रखें। कार्य ID और अंतिम कार्रवाई पर स्थायी विशिष्टता बाधा दो सूचनाएँ भेजने या दो अगली जॉब चलने से रोक सकती है। केवल टाइमस्टैम्प अलग कार्यों की घटनाओं की पहचान के लिए पर्याप्त नहीं है। अंतिम स्थिति के बाद पुराने अपडेट अनदेखे करें और क्रैश के बाद वर्कर का सुरक्षित पुनः प्रयास संभव बनाएँ।

कॉलबैक न आए या स्थिति अस्पष्ट हो तो सहेजी हुई ID दोबारा पढ़ें। पढ़ने का टाइमआउट बिना जाँच दूसरा सशुल्क कार्य बनाने का कारण नहीं है। संचार त्रुटि और पुष्ट कार्य विफलता को अलग रखें; दोबारा जमा करने से पहले स्थिति मिलाएँ।

4. विफलता के मामले जाँचें

रिलीज़ से पहले कॉलबैक दोहराएँ, गलत सीक्रेट भेजें, डिलीवरी में देर करें और वर्कर रीस्टार्ट का अनुकरण करें। हर पूर्ण कार्य से एक स्थायी परिणाम बने और हर विफल कार्य की त्रुटि सुरक्षित रहे। फिर आउटपुट संग्रहण गाइड से फ़ाइलें सुरक्षित रखें।

संदर्भ: एकीकृत API स्कीमा, कार्य पढ़ने का उदाहरण और Webhook दस्तावेज़। उदाहरण एकीकरण की संरचना बताते हैं, वास्तविक जनरेशन का बेंचमार्क नहीं हैं।