توجيه شفاف وتفصيل الرحلة

GetVibe هو موجِّه شفّاف: إما أن تختار صراحةً متغيرًا عامًا عبر لاحقة :alias، أو تترك اسم النموذج دون لاحقة — وعندها يختار البوابة المسار وفق استراتيجية حسابك/مفتاحك، وعند الفشل ينتقل إلى متغير آخر متاح. لا تُستخدم في الاستجابات والسجل سوى معرّفات المسارات العامة.

"model": "claude-opus-4.8"          // auto — key strategy
"model": "claude-opus-4.8:yellow"   // pin — :yellow only, no switching to other channels
"model": "claude-opus-4.8:2"        // pin — catalog variant #2 (legacy :N syntax)

يُخدَم كل نموذج عبر عدة قنوات بأسعار مختلفة — سلّم. هذان المعاملان في جسم الطلب يحدّدان أي درجات من ذلك السلّم يجوز أن تخدمك. كلاهما بالدولار الأمريكي لكل مليون رمز، بالوحدة نفسها والأرقام نفسها التي تعرضها صفحة النماذج. ويُقارنان بـسعرنا — وهو ما تُحتسب به عليك — لا برقم بيع بالجملة لا يمكنك رؤيته.

{
  "model": "deepseek-v4-flash-0731",
  "messages": [{"role": "user", "content": "hi"}],
  "max_price": 0.02,
  "min_price": {"input": 0.001}
}

يجب أن يستوفي الشقّان معًا، الإدخال والإخراج — لا متوسط بينهما أبدًا. فالقناة الرخيصة في الإدخال والمكلفة في الإخراج لا تحقق حدًّا برقم واحد.

حد أقصى دائم يُضبط مرة واحدة في لوحة التحكم

لا يلزم تكرار السقف في كل استدعاء. تخزّن لوحة التحكم سقفًا واحدًا لكل مفتاح API ولكل نموذج، إضافة إلى سقف افتراضي يغطي كل نموذج لم تضبطه صراحةً، ويقرؤه الـ API في كل طلب. والطلب الذي يحمل max_price يستخدم تلك القيمة بدلًا منه لذلك الاستدعاء الواحد؛ والطلب الذي لا يحمل شيئًا يستخدم سقفك المخزَّن. الترتيب بالأولوية، من الأكثر تحديدًا إلى الأقل:

أين تقرأ الأسعار التي تحدّدها كسقف

ينشر GET /api/catalog مصفوفة channels لكل نموذج: عنصر واحد لكل قناة قد يهبط عليها الطلب، من الأرخص إلى الأغلى، ويضم كل عنصر العنوان الذي يمكنك تثبيته به، وسعره inputUsd / outputUsd لكل مليون رمز، وما إذا كانت هي القناة الافتراضية. وهذه هي الأرقام نفسها التي يُقارَن بها max_price و min_price، والأرقام نفسها التي تُحتسب بها فاتورتك — قائمة واحدة، لا ثلاث.

curl -s https://getvibeapi.com/api/catalog   | jq '.[] | select(.apiModel=="z-ai/glm-5.3") | .channels'

ما الذي تُحتسب عليه التكلفة

يُحتسب عليك المسار الذي خدم الطلب فعليًا، مضافًا إليه هامش ربحي الثابت — لا سقف السعر الذي وضعته، ولا يزيد أبدًا عليه. إذا حدّدت سقفًا بسعر وامتلأ الطلب عند درجة أرخص، تدفع الأرخص. يُظهر سلّم الأسعار في صفحة النموذج نطاقًا، ورقم «from» هو أرخص درجة موجودة — وهو سعر حقيقي يمكن أن يُحتسب عليك، لا وعدًا بأن طلبك سيستقر عند تلك الدرجة. اضبط max_price حين تحتاج إلى حدٍّ أعلى مضمون.

عندما لا يناسب أي شيء

يُرفض الطلب refused: HTTP 422 مع "type": "price_bound_no_lane"، مع ذكر أرخص وأغلى سعر قناة لذلك النموذج وقائمة channels الكاملة، لتتمكن من اختيار حدّ من الأرقام بدل تخمينه. lowest_passing_usd_per_million هو أصغر حدّ يقبل قناة الآن — زوج قناة واحدة، لذا فإن إرساله يمرّ (وقد يأتي طرفا cheapest من قناتين مختلفتين). ويظهر الحقل نفسه عندما يرفض التبادل نفسه حدّك: حينها يكون مستوى السعر التالي الذي لا يزال لديه معروض، وهو لا يقل أبدًا عن الحدّ الذي أرسلته. أما عندما لم يكن حدّك هو القيد — بل سقف الشراء الخاص بنا للقناة، وكانت العروض تحته مشغولة أو مستنفدة — فالرد يكون بدلًا من ذلك HTTP 503 "type": "no_seller_available" مع Retry-After ودون سعر مقترح: فرفع max_price لن يفيد، وقد تفيد إعادة المحاولة بعد قليل. كثيرًا ما تحمل أرخص درجة عرضًا واحدًا مشغولًا، لذا لعمليات التعبئة الموثوقة ضع الحدّ عند priceTypical النموذج أو أعلى منه، حيث يوجد معظم المعروض. نحن لا نخدم قناة أغلى بصمت أبدًا، ولا نستبدل نموذجًا آخر. أما القيمة المشوَّهة — نص أو صفر أو قيمة سالبة أو حقل غير معروف — فهي 400 invalid_request_error، ولا تُتجاهل بصمت أبدًا.

{
  "error": {
    "message": "No channel of model "deepseek-v4-flash-0731" is priced within your max_price $0.0001 in / $0.0001 out...",
    "type": "price_bound_no_lane",
    "code": 422,
    "param": "max_price",
    "cheapest_usd_per_million": {"input": 0.0065, "output": 0.013},
    "dearest_usd_per_million": {"input": 0.0528, "output": 0.1584},
    "lowest_passing_usd_per_million": {"input": 0.0205, "output": 0.0613},
    "channels": [
      {"address": "deepseek/deepseek-v4-flash-0731:codebuddy-cn", "label": "codebuddy-cn", "inputUsd": 0.0205, "outputUsd": 0.0613, "isDefault": true},
      {"address": "deepseek/deepseek-v4-flash-0731:qwencloud", "label": "qwencloud", "inputUsd": 0.0378, "outputUsd": 0.1132, "isDefault": false}
    ]
  }
}

القنوات المخدومة من مجمّع اشتراك مورّد يمكن استدعاؤها بالاسم. اكتب الاسم بعد نقطتين، تمامًا كأي اسم مستعار آخر:

"model": "gpt-6.1-sol:codex"         // pin a subscription pool
"model": "claude-opus-5.5:claude-code"  // pin the Claude Code pool

اللاحقة بعد النقطتين هي معرّف مسار عام، وليست اسمًا لدى المزوّد. والقائمة الكاملة لنموذج بعينه موجودة في الكتالوج (Models، عمود «In API»). الأسماء المستعارة الرئيسية:

بالنسبة إلى طلبات auto (اسم النموذج دون لاحقة)، تُضبط الإعدادات التالية لكل مفتاح API (لوحة التحكم ← مفاتيح API):

أضف اسمًا مستعارًا للمزوّد بعد النقطتين الرأسيتين — يُحترم بغض النظر عن استراتيجية التوجيه. القائمة الكاملة للأسماء المستعارة والأمثلة — في قسم Models → Providers.

"model": "claude-opus-4.8"        // auto — key strategy
"model": "claude-opus-4.8:yellow"     // explicitly pin the :yellow channel
"model": "claude-opus-4.8:kiro-pool"  // explicitly pin the :kiro-pool channel

لكل مفتاح API يمكنك ضبط ما يلي في لوحة التحكم:

مع نموذج مجرّد قد تنتقل البوابة إلى متغيّر عام آخر للنموذج نفسه إذا أعاد المتغيّر الحالي 429 أو 5xx أو 200 فارغًا بلا محتوى. القيود:

• لا تُحوَّل الطلبات التي تحتوي على صور/PDF إلى مزوّد آخر (توافق الرؤية).
• التجاوز عند الفشل لا ينتقل إلى متغيّر أعلى سعراً بشكل ملحوظ (عدا استراتيجية price).
• يوجد حدّ أعلى لعدد المحاولات لكل طلب عميل.
• مع pin (:alias) يكون التحوّل الاحتياطي بين المورّدين معطّلًا — فتحصل على خطأ المسار المختار.

تُوصف إعادة المحاولة مع التراجع الأسي عند 429 في الأخطاء والحدود.

بالنسبة إلى عملاء الكشف/التنقيح الموثوقين، تتوفر بعد اكتمال الطلب (بما في ذلك الوضع التلقائي) ترويسات تُظهر أيّ public متغير نُفّذ فعليًا. ولا تُمنح هذه البيانات للعملاء العاديين.

ترويسات الاستجابة لعملاء الكشف/التنقيح الموثوقين (chat / messages / responses)

curl -sD - https://getvibeapi.com/v1/chat/completions \
  -H "Authorization: Bearer $GETVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-6.1-sol","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' \
  -o /dev/null | grep -i getvibe

# x-getvibe-route: yellow
# x-getvibe-model: gpt-6.1-sol:yellow

سجلّ الاستخدام

في GET /v1/generations وGET /v1/usage ولوحة التحكّم، يتضمّن كل سجل الحقول التالية:

لا يوفّر GetVibe قائمة «شلال خام» تُدرج المزوّدين upstream في جسم الطلب. تتم التحكّم عبر :alias العام واستراتيجية المفتاح والتحوّل التلقائي عند الفشل ضمن كتالوج النماذج. لا توجد واجهة برمجية منفصلة «تجاهل المزوّدين» ولا أعلام توجيه ZDR.