دليل تكامل GloopAPI
الفوترة
افهم الحجز والتسوية وتخزين الملفات.
كتالوج النماذج وملخص الأسعار العام وحسابات الاستدعاءات الفعلية معلومات مختلفة. ينبغي للتطبيق التحقق من النموذج أو الأداة والمدخلات والميزانية قبل أي عملية مدفوعة؛ فوجود رصيد كافٍ لا يعني امتلاك صلاحية الاستدعاء.
الحجز والتسوية
قد يُحجز مبلغ تقديري عند قبول الطلب، ثم تُجرى التسوية بالأسعار المثبّتة عند وصول بيانات الاستخدام المعتمدة، مع خصم الفرق أو إعادته. عرض سعر الفيديو حسب الاستخدام تقديري وليس التزامًا بحد أقصى للإنفاق. يُحسب أقصى حجز للأداة وفق حدود المدخلات والقواعد المثبّتة، ويُراجع سقف التكلفة عند الإنشاء.
تصف status=succeeded نتيجة التنفيذ، بينما تعني billing.status=reserved أن التكلفة ما زالت تنتظر التأكيد. المبلغ النهائي الفارغ لا يعني صفرًا. الإرسال المجهول للخدمة أو بيانات الاستخدام المتعارضة تُبقي الحجز حتى المراجعة؛ ويعتمد رد المبلغ بعد الفشل المؤكد على الواجهة وأدلة الاستخدام، ولا يمكن ضمان أن جميع حالات الفشل مجانية.
للنص المتزامن، راجع الاستهلاك النهائي في سجلات استخدام المنصة؛ وللمهام غير المتزامنة راجع حالتها المالية. لا تحاول تسوية مهمة قديمة بتوليد جديد.
إمكانات تسعير الأدوات
يميز pricing.mode بين flat للسعر الثابت لكل استدعاء، وinput للحساب المسبق حسب المدخلات، وusage للحساب حسب الاستخدام النهائي. يشير schema_version إلى تنسيق القاعدة فقط. amount في flat هو السعر الثابت الكامل، بما فيه الصفر؛ ولا توفر input/usage مبلغًا ثابتًا مضللًا.
يحدد pricing.quote_required ما إذا كان الاستدعاء الجديد يحتاج إلى عرض سعر؛ ويحدد requires_usage ما إذا كانت التسوية النهائية تتطلب بيانات استخدام معتمدة، بما يشمل قيود تسوية المنصة. حتى مع سعر بيع flat قد يلزم عرض سعر واستخدام نهائي؛ اتخذ القرار وفق هذين الحقلين. عند requires_usage=true يجب إرسال max_cost_usd يغطي maximum_usd، ثم انتظار الاستخدام المعتمد بعد النجاح قبل التسوية. قواعد input التي لا تحتاج إلى استخدام نهائي يمكن تسويتها بمبلغ المدخلات بعد عرض السعر دون انتظار بيانات الخدمة.
يقيّد metered_pricing الاستدعاءات الجديدة التي تحتاج إلى استخدام نهائي فقط. لا يقيّد القواعد الثابتة أو المبنية على المدخلات التي لا تحتاج إليه، ولا يمنع استعلام التشغيل المقبول أو إعادة الطلب الأصلي بضمان عدم التكرار أو استعادة الحسابات المثبّتة. يرتبط العرض بـ Key وإصدار الأداة والمدخلات الموحّدة وإعدادات السعر والمصدر. يُراجع quote_id المقدم دائمًا حتى للأدوات ذات السعر الثابت. ظهور أدنى شريحة في الكتالوج لا يعني أن الأداة مجانية.
الاحتفاظ بالملفات والمساحة
تنتهي صلاحية ملفات API العادية المؤرشفة حسب مدة الاحتفاظ المضبوطة في النشر. تُحفظ الصور والفيديوهات الدائمة طويلًا بفضل حماية المراجع؛ وتعني expires_at=0 عدم وجود موعد انتهاء محدد. يُحسب استخدام مساحة التخزين ورسوم التوليد منفصلين، ولا يُضمن التنزيل قبل ready.
حذف مهمة دائمة يفرغ نتائجها ويفك المراجع القابلة للحذف، ثم تُنظف الملفات غير المشتركة في الخلفية. تبقى المراجع المشتركة وسجلات الحسابات وعدم التكرار محفوظة. حذف ملف أو فشل حفظه لا يعيد تلقائيًا رسوم التوليد المستحقة. إعادة محاولة الحفظ تطلب المساحة المتاحة وتستخدم النتيجة الأصلية دون توليد جديد.
عدم كفاية الحصة
عند 403 أو 402 أو خطأ حصة، تحقق أولًا من حدود الحساب وKey. تسمح المصادقة الدائمة للمفتاح الصالح المنفد بقراءة السجل، لكن المهام الجديدة تظل بحاجة إلى ميزانية. لتسوية مهمة أصلية، واصل الاستعلام عن سجلها الأصلي؛ لا تعِد تقديمها بتغيير Key أو مفتاح الطلب. راجع المصادقة والمهام غير المتزامنة وضمان عدم تكرار التنفيذ.