الحدود والحصص

ما يحدّ استدعاءاتكم، وكيفية قراءته من شيفرتكم. كل هذه الحدود مُدارة : تتغير دون إعادة نشر، لذا يجب أن تقرأها شيفرتكم بدل افتراضها.

المعدل#

يحمل كل مفتاح معدلًا بالطلبات في الدقيقة وعددًا من الاستدعاءات المتزامنة. كلاهما مرتبط بالمفتاح، لا بالحساب : فصل مفاتيحكم حسب البيئة يمنع سكربت اختبار من تجويع إنتاجكم.

عند بلوغ المعدل، تكون الاستجابة 429 وتحمل Retry-After، بالثواني. احترموها. إعادة المحاولة أبكر لا تُسرِّع شيئًا وتفاقم الحمل في اللحظة التي يحتاجها الخدمة أقل.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

وإن أعدتم المحاولة، أضيفوا بعض العشوائية إلى انتظاركم. بدون ذلك، ستعود كل عملياتكم المحظورة في نفس اللحظة معًا ؛ هذا ما يحوّل تباطؤًا عابرًا إلى عطل.

حجم الطلبات#

جسم الطلب محدود. بعد ذلك، تكون الاستجابة 413 حتى قبل قراءة المحتوى : الرفض المبكر أرخص من تحميل شيء سيُرفَض في الذاكرة.

لمستند ضخم، مروا عبر API الملفات وأشيروا إلى المعرّف. هذا ما صُمِّمت له.

نافذة السياق والإخراج#

لكل نموذج نافذة سياقه وسقف رموزه المُنتَجة. لا تثبّتوها في الشيفرة : تُقدَّم عبر GET /v1/pricing، وهذا هو المصدر الوحيد الذي يقول ما تطبّقه البوابة فعليًا.

curl https://api.cloudzir.com/v1/pricing

{
  "object": "list",
  "data": [
    {
      "model": "mina-flash",
      "currency": "DZD",
      "unit": "per_million_tokens",
      "input": 250.0,
      "cached_input": 8.0,
      "output": 700.0,
      "context_window": 64000,
      "max_output_tokens": 8192,
      "description": "Tout ce que fait Mina, à la vitesse maximale et au coût le plus bas. Le bon choix quand la réponse doit être immédiate et le volume élevé."
    }
  ]
}

يعرض المثال نموذجًا واحدًا فقط : تحتوي القائمة على كائن واحد لكل نموذج مفعّل.

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

الرصيد#

رصيد صفري يتسبب في 402 على كل الاستدعاءات المفوترة التالية. راقبوه بواسطة نقطة الرصيد بدل اكتشاف الانقطاع في الإنتاج.

يُعاد total_balance كـسلسلة نصية بأربع خانات عشرية، لا كرقم عشري. ليست هذه غرابة : رقم عشري سيفقد سنتيمات في كل قراءة، ورصيد ينحرف ببضع سنتيمات يوميًا ينتهي به المطاف لا يطابق سجلاتكم.

التخزين المؤقت#

تُفوتَر رموز الإدخال المُشاهَدة سابقًا بسعر cached_input، الأقل بكثير. تُفصِّل كتلة usage في كل استجابة ما خُزِّن مؤقتًا :

"usage": {
  "prompt_tokens": 148,
  "completion_tokens": 12,
  "total_tokens": 160,
  "prompt_tokens_details": { "cached_tokens": 96 },
  "prompt_cache_hit_tokens": 96,
  "prompt_cache_miss_tokens": 52
}

هذه الحقول موجودة لتتمكنوا من التحقق مما يُحتسَب عليكم، لا فقط لمراقبته. انظروا التخزين المؤقت للسياق لبناء طلباتكم بطريقة تستفيد منه.

ما ليس حدًا تقنيًا#

الحصص التجارية لباقة ما : عدد الرسائل، غلاف التوليدات؛ تختلف عن الحدود أعلاه. الأولى تخصيصات، قابلة للمراجعة من الإدارة. الثانية ضمانات حماية : تحمي الخدمة، ولا يمكن لأي تخصيص تجاري تعطيلها.