دليل تكامل GloopAPI
المهام غير المتزامنة ومنع التكرار
استرد المهام وعالج الإرسالات غير المعروفة.
يمثل مفتاح عدم التكرار عملية تجارية واحدة في تطبيقك. احفظ نص الطلب وهوية Key ومفتاح الطلب بشكل دائم قبل الإرسال؛ وعند إعادة الإرسال استخدم المفتاح نفسه والمدخلات الموحّدة نفسها. تغيير الطلب مع استخدام المفتاح نفسه يسبب تعارضًا، بينما تغيير المفتاح ينشئ عملية جديدة مدفوعة.
عرض السعر والإنشاء
للصور والفيديوهات الدائمة، اقرأ أولًا كتالوج الإمكانات، ثم ارفع المدخلات أو استوردها، واحصل على عرض سعر وأكّد الإنشاء صراحةً. عروض أسعار الصور والفيديو صالحة لمدة 60 ثانية، وعروض الأدوات لمدة 300 ثانية؛ ويحدد expires_at من الخادم الموعد الفعلي. عرض السعر لا يرسل طلبًا إلى الخدمة ولا يفرض رسومًا. للاستدعاءات الجديدة التي لم تُرسل، اطلب عرضًا جديدًا عند انتهاء العرض أو تغيّر المدخلات أو الإعدادات، وراجع التكلفة الجديدة قبل الإنشاء. أما إذا أُرسل الطلب وأصبحت النتيجة مجهولة فلا تعدّل العرض أو الطلب الأصلي.
عرض سعر الصورة لا يقفل أصول الإدخال، وتُراجع مجددًا عند الإنشاء. يسمح الفيديو فقط باستخدام preset كامل وإطارات مستضافة تتوافق مع الوضع الحالي. أرسل retention: "persistent" صراحةً للفيديو الدائم؛ ويظل الفيديو العادي ملتزمًا بعقد مدخلات URL الخاص به.
اتخاذ القرار عند جهل نتيجة الإرسال
بعد الحصول على معرّف المهمة، استعلم فقط عن المهمة الأصلية. إذا انتهت المهلة دون معرّف، فاستخدم واجهات الاستعادة بمفتاح الطلب الأصلي للصور والفيديوهات الدائمة. إذا وُجد سجل للمهمة فتابع مراقبته. الحالات unknown أو submission_unknown أو submission_state_unknown أو billing_review أو انتظار المراجعة لا تعني فشلًا أو استردادًا، ولا تسمح بتغيير المفتاح وإعادة التوليد.
إذا كان للأداة run_id فاستعلم باستخدام Key الأصلي. إذا ضاعت استجابة الإنشاء ولم يوجد run_id، فأعد POST /v1/tool-runs باستخدام API Key وIdempotency-Key ونص الطلب الكامل الأصلي، مع إبقاء quote_id/version/input/max_cost_usd كما هي. التشغيل المقبول سابقًا يستعيد سجله الأصلي مباشرةً، دون الحاجة إلى عرض جديد أو الاعتماد على مفاتيح التفعيل الحالية، ودون إعادة الإرسال للخدمة. يُرتّب السجل تنازليًا حسب created_at ثم id؛ ويجب تمرير next_cursor دون تغيير. التقليب بين الصفحات ليس لقطة ثابتة؛ حدّث الصفحة الأولى لرؤية السجلات الجديدة السابقة للمؤشر. استنساخ الصوت لا يوفّر واجهة الاستعادة نفسها بمفتاح الطلب؛ احتفظ بالأدلة وافحص الإرسال المجهول، ولا تستخدم مسار استعادة الصور.
ثلاث حالات مستقلة
قيّم نجاح التوليد واكتمال التسوية المالية وجاهزية التخزين كلًا على حدة. قد تنجح الصور جزئيًا، وقد تنجح الأداة قبل تأكيد الاستخدام النهائي، وقد يُولّد الفيديو بنجاح ثم يفشل حفظه. تواصل العمليات الخلفية تنفيذ المهام الدائمة؛ إغلاق المتصفح أو إيقاف الاستعلام الدوري من العميل لا يعني الإلغاء.
الإلغاء مجرد طلب، وقد لا يكون مدعومًا أو يصل بعد فوات الأوان. استمر في مراقبة الحالة النهائية والحسابات. عمليات التخزين retry/archive-retry تحفظ النتيجة الأصلية فقط ولا تولّد محتوى جديدًا. حذف المهمة يتطلب حالة نهائية وحسابات نهائية، وتظل أدلة عدم التكرار والتكلفة محفوظة بعد الحذف.
بعد الحصول على النتيجة، تحقق أولًا من أن التخزين ready، ثم احصل على رابط تنزيل مؤقت. انتهاء رابط الخدمة المؤقت قد يجعل الأرشفة غير قابلة للاستعادة؛ لا تخفِ خطأ حفظ المهمة الأصلية بتوليد جديد. راجع الفوترة ومعالجة الأخطاء.