فواتير وأخطاء OpenAPI

تنطبق هذه الصفحة على /api/v1/data/*، وهي واجهات Felo OpenAPI الحصرية للمنصة. تستخدم الاستدعاءات رصيد المنصة، وهو رصيد خدمة مقوَّم بالدولار الأمريكي. وهي لا تستهلك أرصدة Felo Pro. أما واجهات Felo API الأقدم تحت /v2 فتستخدم أرصدة Pro.

اقرأ الأسعار الحالية

curl -sS https://openapi.felo.ai/api/v1/data/prices

لا تتطلب هذه النقطة العامة مفتاحًا. طابق عناصرها حسب معرّف العملية واقرأ السعر الحالي ووحدة الفوترة؛ لا تفترض أن كل عملية تكلف الشيء نفسه، ولا تثبت سعرًا من مثال داخل تطبيقك.

إن كون استعلام الحالة مجانيًا لا يجعل الإنشاء أو التصدير الأساسيين مجانيين. بالنسبة إلى X، قد يزيد الترقيم والسجلات المتداخلة المُعادة من الاستخدام القابل للفوترة.

الرصيد والحجوزات

قبل التنفيذ، قد تحجز الخدمة ما يكفي من الرصيد للعملية. تُسوّى الأعمال الناجحة مقابل ذلك الحجز؛ ويؤدي الفشل المؤكد إلى تحريره. بالنسبة للمهام غير المتزامنة، لا يعني إرجاع معرّف أن الفوترة قد أصبحت نهائية بالفعل.

يحجز تسعير صفحات PPT عشر صفحات عند الإنشاء. يحدد الإنشاء الناجح المخرجات الفعلية ويحرر الأموال غير المستخدمة. الإنشاء والتصدير رسوم منفصلة. راجع سير عمل PPT لسلوك إعادة التصدير.

إذا كان التنفيذ أو التسوية غير مؤكدين، فقد يظل الحجز معلقًا بينما تقوم الخدمة بالمطابقة. لا تعتبر كل مهلة زمنية أو 5xx دليلًا على أن لا شيء حدث أو أن الطلب المتكرر مجاني.

راجع رصيدك المتاح واستخدامك في Console Billing. للحصول على إرشادات الشحن على مستوى الحساب، راجع الفوترة والأرصدة.

استعلم عن استخدام المحفظة عبر API

يمكن لمالكي الحساب فحص سجلات استدعاءات المحفظة باستخدام رمز دخول Felo. يختلف هذا الاعتماد عن مفتاح API المستخدم لاستدعاءات Data API؛ لا تستبدل FELO_API_KEY.

curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'

توجد السجلات تحت data.items; ويرشح call_type=data استدعاءات الإمكانات. قارن الاستخدام مع الأسعار الحالية للحساب. قراءة السجلات لا ترسل مهمة إنشاء أخرى. يظل Console Billing متاحًا لمراجعة الحساب وإجراء الشحن.

اقرأ الأخطاء بحذر

تحقّق من حالة HTTP أولًا. يمكن أن تستخدم الأخطاء أحد الشكلين التاليين؛ والقيم أدناه توضيحية:

{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}

{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}

اقرأ error.code / error.message عندما تكون موجودة، وإلا فاقرأ code / message. احتفظ بـ request_id عند إعادته. تختلف الاستجابات الناجحة بحسب العملية؛ لا تُجبرها جميعًا على نفس الغلاف الخاص بالخطأ أو data.

قرر ما الذي يجب فعله بعد ذلك

تحتاج execution_unconfirmed (409) وbilling_settlement_pending (503) إلى عناية خاصة: لا تعِد إرسال العمل المدفوع فورًا. استعلم عن المهام المعروفة أو تواصل مع الدعم مع معرف الطلب. تختلف الاستجابة الناجحة لحالة HTTP مع نتيجة فارغة عن استجابة الخطأ.

أعد المحاولة دون إنشاء عمل مكرر

• بالنسبة لاستعلامات المهام للقراءة فقط واستعلامات حالة التصدير، استخدم تراجعًا متدرجًا محدودًا وراعِ Retry-After عندما يكون موجودًا.
• عند فشل طلب إنشاء مع task_id محفوظ، استعلم عن تلك المهمة قبل إنشاء واحدة أخرى.
• إذا فشل الاتصال قبل أن تتلقى معرّفًا، فقد تكون النتيجة غير معروفة. لا تفترض أن إعادة الإرسال ستمنع تكرار الطلب.
• بالنسبة إلى 429، فرّق بين حد معدل قصير ونافذة حصة مفتاح API؛ فإعادة المحاولة المتكررة لا يمكنها إعادة ضبط الحصة.
• أوقف المحاولات بعد مهلة نهائية مُهيأة وأظهر خطأً قابلًا للتنفيذ للمتصل.

للدعم، قدّم نقطة النهاية، والوقت التقريبي، وحالة HTTP، ومعرف الطلب. لا تُدرج أبدًا مفتاح API الكامل.