آلية العمل

تُحدد الصيغة بمسار الطلب، لا بالنموذج. يمكن استدعاء نموذج Claude نفسه عبر OpenAI Chat أوOpenAI Responses أوAnthropic Messages؛ ويأتي الرد بصيغة المسار الذي استدعيته.

• قبل إرسال طلب نصي جديد، يحجز Ailoot مبلغًا تقديريًا لتكلفة الإدخال ورد نموذجي، مع مراعاة الحد (max_tokens) وشروط النموذج المحدد. إذا تجاوز المبلغ المحجوز الرصيد الحر أو حد المفتاح، فلا يجوز خفض الحد المرسل إلا لنموذج وطريقة يلتزمان به فعليًا، ودون النزول عن 256 توكن ولا عن الحد الأدنى المقرر للرد. أما الصور والفيديو والصوت في المخرجات، فتظل تكلفة النتيجة كاملة محجوزة.
• بعد الرد، يُخصم مرة واحدة بحسب الاستخدام الفعلي. يُعاد المبلغ المحجوز غير المستخدم إلى الرصيد فوراً.
• إذا كانت تكلفة الرد أعلى من المبلغ المحجوز، يُغطى الفرق من الرصيد المتاح. لا يصبح الرصيد سالباً أبداً.
• إذا لم يكفِ المال حتى للحد الأدنى من الحجز، فلا يُرسل الطلب؛ وتتلقى خطأ 402 مفهوماً دون خصم أي مبلغ.
• لا تُحسب تكلفة خطأ لا ينتج عنه نتيجة.

التفاصيل والمثال الحسابي موجودان في صفحة حجز الرصيد والخصم.

يحصل كل رد على معرّف طلب في الترويسة X-Request-ID وفي نص الخطأ. تأتي الأخطاء بصيغة JSON للواجهة التي استدعيتها، ولذلك تتعرف حزم SDK عليها بصورة صحيحة. إذا حدثت مشكلة، فأرسل Request ID إلى الدعم — وسنتمكن من العثور على الطلب خلال دقيقة.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

تصل الردود المتدفقة (stream: true) بصيغة Server-Sent Events. يعيد Ailoot الرد النصي المدفوع بعد احتساب التكلفة. لذلك عند استخدام stream: true تبقى الصيغة متدفقة (SSE)، لكن النص يأتي دفعة واحدة عند اكتمال النموذج، ولا يصل كلمة بكلمة. إذا استغرق إعداد الرد أكثر من نحو 15 ثانية، تبدأ تدفقات Chat Completions وResponses وMessages بأسطر خدمية : ping (كل 10 ثوانٍ تقريباً)، ثم السطر : ailoot-charged-usd … بمبلغ الخصم، ثم البيانات نفسها. تتجاهل حزم SDK هذه الأسطر.

لا توجد أسطر خدمية في صيغة Gemini؛ ويصل الرد :streamGenerateContent كاملاً بعد الحساب. اضبط مهلة العميل بهامش كافٍ لنماذج الاستدلال؛ عدة دقائق أمر طبيعي.

X-Request-ID يأتي في كل رد. يضيف Ailoot بقية الترويسات إلى الردود النصية المدفوعة:

إذا بدأ التدفق بأسطر خدمية بالفعل، فتأتي هذه المعلومات كسطر تعليق قبل البيانات بدلاً من ترويسة.

إذا دعم النموذج التخزين المؤقت، فقد تقل تكلفة إعادة إرسال بادئة طويلة (تعليمات النظام والمستندات). تظهر أسعار قراءة الذاكرة المؤقتة والكتابة فيها في بطاقة النموذج في الكتالوج. يحدد مطوّر النموذج الاستفادة من التخزين المؤقت، ولا يضمنها Ailoot.