Tovanix
Tovanix

استخدام بوابة API للذكاء الاصطناعي

استدعِ نماذج عدة مزوّدين بمفتاح API واحد، ويُخصم المقابل من رصيد الحساب حسب الاستخدام الفعلي:

  • أنشئ المفتاح في «خدمات الذكاء الاصطناعي ← بوابة API ← مفاتيح API»، واختر مجموعة التسعير لكل مزوّد، ويمكنك ضبط حد إنفاق شهري وتعديله لاحقًا من قائمة المفاتيح
  • تُدعم ثلاثة تنسيقات للطلبات: OpenAI وAnthropic وGemini، وعادةً لا يلزم للتكامل إلا تغيير عنوان البوابة والمفتاح
  • السعر = السعر الرسمي × معامل مجموعة التسعير، ولبعض المجموعات أسعار لأوقات خارج الذروة
  • يُحجز مبلغ قبل الاستدعاء ويُسوّى بعد انتهائه حسب الاستخدام الفعلي، ويُخصم من الرصيد مجمّعًا مرة كل دقيقة
  • توفر «الاستخدام والسجلات» الإحصاءات وتفاصيل كل استدعاء على حدة

الغرض من البوابة

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

  • تعمل حزم SDK الرسمية كما هي: التكامل يعني غالبًا تغيير base_url و api_key فقط، مع بقاء بنية الطلب والرد دون تغيير.
  • تُدعم ثلاثة تنسيقات للطلبات: OpenAI وAnthropic وGemini، ويمكن الاستدعاء عبر التنسيقات، كأن تستدعي نماذج Claude بـ SDK الخاص بـ OpenAI، فتتولى البوابة التحويل تلقائيًا.
  • التسعير حسب مجموعة التسعير: للنموذج الواحد سعر واحد داخل المجموعة الواحدة. إذا كانت في المجموعة عدة مسارات وتعطّل أحدها، يُحوَّل الطلب تلقائيًا إلى المسار التالي في المجموعة نفسها، ويبقى السعر كما هو.

إنشاء مفتاح API

  • افتح صفحة مفاتيح API: في لوحة التحكم افتح «خدمات الذكاء الاصطناعي ← بوابة API ← مفاتيح API»، ثم اضغط «إنشاء مفتاح» في أعلى الصفحة.
  • عيّن الاسم ومجموعة التسعير والحد الشهري: يُستحسن تسمية المفتاح حسب الاستخدام، مثل production أو test أو cursor. لكل مزوّد تتوفر له أكثر من مجموعة، اختر «مجموعة التسعير» على حدة، وإن لم تختر تُستخدم مجموعته الافتراضية. ترك حد الإنفاق الشهري فارغًا يعني بلا حد، وإدخال 0 يعني عدم السماح بأي إنفاق هذا الشهر؛ ويمكنك تعديل الحد لاحقًا من قائمة المفاتيح عبر «تغيير الحد»، ويتطلّب ذلك التحقق من هويتك.
  • تحقّق من هويتك: بعد الضغط على «إنشاء» يلزم التحقق من هويتك: إذا كان التحقق بخطوتين (2FA) مفعّلًا فأدخل الرمز المتغيّر المكوّن من 6 أرقام من تطبيق المصادقة؛ وإلا فأدخل رمز التحقق المرسل إلى بريدك. بعد نجاح التحقق، لا يلزم تكراره لإنشاء مفاتيح أخرى أو تغيير الحد خلال 10 دقائق في جلسة الدخول نفسها.
  • احفظ المفتاح الصريح فورًا: يبدأ المفتاح بـ sk-nc- ثم سلسلة، ويظهر مرة واحدة لأن الخادم يحفظ بصمته فقط. انسخه إلى مدير كلمات المرور قبل إغلاق النافذة.

بمجرد إغلاق تلك النافذة يختفي النص الصريح نهائيًا — المنصة تحتفظ ببصمة لا بالمفتاح نفسه. إذا لم تحفظه فالخيار الوحيد هو حذف المفتاح وإنشاء آخر. الحذف يسري فورًا وكل ما يستخدم ذلك المفتاح سينقطع.

مجموعات التسعير

تحدّد مجموعة التسعير السعر الذي يُحتسب به استدعاء هذا المفتاح لنماذج مزوّد معيّن: السعر = السعر الرسمي × معامل المجموعة. تُقسَّم المجموعات حسب المزوّد، ولكل مزوّد مجموعاته الخاصة ومجموعة افتراضية.

  • عند إنشاء المفتاح، لا يلزم الاختيار إلا للمزوّدين الذين لديهم مجموعتان أو أكثر؛ أما من له مجموعة واحدة فلا يلزم الاختيار له. والمزوّد الذي لم تختر له مجموعة تُستخدم له مجموعته الافتراضية.
  • يعرض عمود «المجموعة» في قائمة المفاتيح المجموعة المختارة لكل مزوّد ومعاملها؛ ويمكنك تغييرها بالضغط على «تغيير»، فيُحتسب السعر وفق المجموعة الجديدة بدءًا من الاستدعاء التالي.
  • لا تمرّ الاستدعاءات إلا عبر مسارات المجموعة المختارة، ولا تنتقل إلى مجموعة أخرى، لذا لا يتغيّر سعر النموذج نفسه بسبب تغيّر المسار.

إذا عُطّلت المجموعة المختارة لمزوّد ما، تظهر «المجموعة معطّلة» في القائمة، ويُرفض استدعاء نماذج ذلك المزوّد بهذا المفتاح (HTTP 403). اضغط «تغيير» واختر مجموعة أخرى.

إجراء أول استدعاء

عنوان البوابة هو النطاق نفسه الذي تعمل عليه لوحة التحكم. تعرض صفحة «لوحة المعلومات» أمثلة curl بالتنسيقات الثلاثة OpenAI وAnthropic وGemini، وتتضمن نافذة نجاح إنشاء المفتاح مثالًا أيضًا، وعنوان البوابة مملوء فيها جميعًا.

  • OpenAI — ⁦/v1/chat/completions⁩ — ترويسة الطلب Authorization، وقيمتها Bearer متبوعة بمفتاحك
  • Anthropic — ⁦/v1/messages⁩ — ترويسة الطلب ⁦x-api-key⁩
  • Gemini — ⁦/v1beta/models/اسم النموذج:generateContent⁩، وللبث ⁦:streamGenerateContent⁩ — ترويسة الطلب ⁦x-goog-api-key⁩، أو معامل العنوان ⁦?key=⁩
  • في SDK الرسمي، وجّه base_url إلى البوابة وعيّن api_key بهذا المفتاح؛ يبقى باقي الكود كما هو.
  • وتتوفر كذلك ⁦/v1/models⁩ (سرد النماذج المتاحة) و⁦/v1/embeddings⁩ (متجهات النصوص) و⁦/v1/images/generations⁩ (توليد الصور، ويُحتسب لكل صورة)، وتُستدعى جميعها بتنسيق OpenAI.
  • اكتب في الحقل model من الطلب معرّف النموذج الظاهر على بطاقته في «سوق النماذج». إذا كان المعرّف خاطئًا أو لم يكن النموذج معروضًا، يُعاد 404.

سوق النماذج وعرض الأسعار

يسرد «سوق النماذج» جميع النماذج المتاحة حسب المزوّد، مع البحث بالاسم أو slug أو الوصف أو القدرة، وعرض السياق وأقصى إخراج وغيرها من الخصائص.

  • السعر = السعر الرسمي × معامل مجموعة التسعير. تعرض علامة التبويب «الكل» الأسعار حسب المجموعة الافتراضية لكل مزوّد؛ وعند فتح مزوّد بعينه يمكنك التبديل بين مجموعاته. والمضاعف الظاهر في الزاوية العلوية من البطاقة هو معامل المجموعة الحالية.
  • النماذج المسعّرة بالرموز يُعرض لها بندان: الإدخال والإخراج، والوحدة لكل مليون رمز؛ وما له سعر لقراءة الذاكرة المؤقتة يُفرد له سطر مستقل. أما نماذج الصور والصوت والفيديو وغيرها مما يُسعَّر لكل صورة أو ثانية أو دقيقة أو استدعاء، فيُكتب سعر الوحدة مباشرةً على البطاقة.
  • تعرض بطاقات بعض النماذج سطرًا بسعر «مطالبات تتجاوز» طولًا معيّنًا: إذا تجاوزت مطالبة الطلب الواحد هذا الطول، يُحتسب الطلب كله بسعر هذا السطر.
  • النماذج التي تعرض بطاقاتها سطر «البحث على الويب» يُحتسب فيها استخدام البحث على الويب المدمج في النموذج بشكل إضافي حسب عدد عمليات البحث.

إذا كان للمجموعة سعر خاص بأوقات خارج الذروة، تحمل البطاقة وسم «خارج الذروة» مع المعامل، وعند تمرير المؤشر فوقه تظهر أوقات الذروة؛ وخارج أوقات الذروة يُضرب سعر المجموعة في هذا المعامل، ويُحدَّد ذلك بلحظة إرسال الطلب. إذا حملت البطاقة وسم «لا توجد مسارات في هذه المجموعة بعد» فإنها تسرد المجموعات التي يمكن استخدام النموذج من خلالها؛ ووسم «غير متاح حاليًا» يعني أنه لا يمكن استدعاؤه حاليًا من أي مجموعة.

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

في «خدمات الذكاء الاصطناعي ← بوابة API ← الاستخدام والسجلات» يضم النصف العلوي الإحصاءات، ويمكن التبديل بين 24 ساعة و7 أيام و30 يومًا و90 يومًا، والافتراضي 7 أيام؛ ويضم النصف السفلي تفاصيل الاستدعاءات.

  • الإحصاءات: عدد الطلبات، والمبلغ المفوتر، وإجمالي الرموز (بما فيها الجزء المخزّن مؤقتًا)، ونسبة النجاح، ومتوسط زمن الاستجابة، إضافة إلى الاتجاه اليومي والترتيب حسب النموذج وحسب المفتاح.
  • التفاصيل: لكل استدعاء الوقت والنموذج وهل هو بث، ورموز الإدخال / الإخراج / الذاكرة المؤقتة، والمبلغ المفوتر والمعامل والزمن والحالة، مع التصفية حسب slug النموذج.
  • لا تسجّل التفاصيل إلا الاستدعاءات التي وصلت إلى النموذج، وحالتها «نجاح» أو «خطأ»، ولا تُحتسب سجلات «خطأ». الطلبات المرفوضة قبل وصولها إلى النموذج (مثل مفتاح غير صالح، أو بلوغ الحد الشهري، أو عدم كفاية الرصيد، أو تعطيل المجموعة) لا تظهر في التفاصيل، وسببها مذكور في رسالة الخطأ التي تعيدها الواجهة.
  • يعرض عمود «المعامل» معامل المجموعة دون احتساب خصم أوقات خارج الذروة؛ والمعتمد فيما خُصم فعليًا في كل مرة هو عمود «المبلغ المفوتر USD».

كيف تُحاسب

يُخصم المقابل من رصيد الحساب حسب الاستخدام الفعلي، دون حاجة إلى شحن منفصل لهذه الخدمة. تكلفة كل استدعاء = السعر الرسمي × معامل المجموعة؛ وإذا كانت للمجموعة أوقات خارج الذروة، يُضرب السعر خلالها في معامل خارج الذروة أيضًا، ويُحدَّد ذلك بلحظة إرسال الطلب.

  • قبل الاستدعاء يُحجز مبلغ وفق طول الإدخال في هذا الطلب وأقصى إخراج للنموذج، وبعد الانتهاء يُسوّى حسب الاستخدام الفعلي ويُحرَّر الفائض. إذا لم يكفِ الرصيد المتاح لهذا الحجز يُعاد خطأ عدم كفاية الرصيد (HTTP 402)، وتوضّح رسالة الخطأ المبلغ المطلوب حجزه هذه المرة والمبلغ المتاح حاليًا.
  • تتراكم التكاليف استدعاءً بعد استدعاء، وتُخصم من الرصيد مجمّعةً مرة كل دقيقة؛ وفي فواتير «الشؤون المالية» يُنشأ كل ساعة سطر «استخدام خدمات الذكاء الاصطناعي (ملخص 1 ساعة)».
  • عندما ينخفض الرصيد المتاح إلى 5 دولارات أو أقل، تنبّهك المنصة مرة واحدة عبر قنوات الإشعار مثل رسائل الموقع؛ وإذا عاد فوق 5 دولارات ثم انخفض مجددًا، يصلك تنبيه آخر. وخلال ذلك تحمل ردود الواجهة الترويستين ⁦X-Tovanix-Balance-Low: 1⁩ و⁦X-Tovanix-Balance-Available⁩ (المبلغ المتاح حاليًا)، ويمكن لبرنامجك الاعتماد عليهما للتذكير بالشحن مسبقًا.
  • يمكن ضبط حد إنفاق شهري لكل مفتاح على حدة، يُحسب حسب الشهر الميلادي ويُستعاد تلقائيًا في الشهر التالي. يُفحص الحد قبل كل استدعاء: إذا بلغ ما أُنفق هذا الشهر مضافًا إليه الاستدعاءات الجارية الحد، فلا يُسمح بالمزيد؛ ولأن آخر استدعاء يُسوّى حسب الاستخدام الفعلي، فقد يتجاوز إنفاق الشهر الحد بقليل.

تنبيهات

  • لا يظهر المفتاح الصريح إلا وقت الإنشاء؛ احفظه فورًا.
  • يسري حذف المفتاح فورًا ولا يمكن استعادته. إذا أردت إيقافه مؤقتًا فقط، فاضغط «تعطيل» في القائمة، ويمكنك بعد ذلك الضغط على «تفعيل».
  • يمنع الحد الشهري 0 المفتاح كامل الشهر؛ لا تستخدمه بمعنى بلا حد.
  • تعالج البوابة الطلبات بالفئة القياسية: تُتجاهل فئة السرعة المحددة في الطلب (مثل ⁦speed: fast⁩ في Claude و⁦service_tier⁩ في OpenAI)، وتُحتسب التكلفة بالسعر القياسي.
  • عند الاستدعاء بتنسيق Anthropic مع أداة البحث على الويب، إذا لم يحدد الطلب حدًا لعدد عمليات البحث، فالحد الأقصى 10 عمليات بحث لكل طلب.

استكشاف الأخطاء

  • يُعاد 401 مع رسالة تفيد بأن المفتاح غير صالح أو معطّل — المفتاح مكتوب خطأً أو محذوف أو معطّل — تأكّد في صفحة «مفاتيح API» أن حالة المفتاح «مفعّل»، وإذا كان معطّلًا فاضغط «تفعيل»؛ أما المفتاح المحذوف فلا يمكن استعادته، ولا سبيل إلا إنشاء مفتاح جديد.
  • يُعاد 402 مع رسالة تفيد ببلوغ حد الإنفاق الشهري — بلغ إنفاق هذا المفتاح هذا الشهر الحد (الحد 0 يعني عدم السماح بأي إنفاق هذا الشهر) — يُستعاد تلقائيًا في الشهر التالي. وإن لم تستطع الانتظار، فاضغط «تغيير الحد» لهذا المفتاح في صفحة «مفاتيح API» وارفع الحد أو اترك الحقل فارغًا لإلغائه (يتطلّب التحقق من هويتك)؛ ويُطبَّق الحد الجديد بدءًا من الاستدعاء التالي.
  • يُعاد 402 مع رسالة تفيد بعدم كفاية الرصيد — الرصيد المتاح لا يكفي للمبلغ المحجوز لهذا الطلب — توضّح رسالة الخطأ المبلغ المطلوب حجزه هذه المرة والمبلغ المتاح حاليًا؛ اشحن رصيدك ثم أعد المحاولة.
  • يُعاد 403 أو 503 مع رسالة تفيد بتعطيل المجموعة أو بعدم توفر مسار متاح — عُطّلت المجموعة التي اختارها المفتاح لهذا المزوّد، أو لا يتوفر حاليًا مسار متاح لهذا النموذج في المجموعة — اضغط «تغيير» في صفحة «مفاتيح API» واختر مجموعة أخرى؛ وتسرد بطاقة النموذج في «سوق النماذج» المجموعات التي يمكن استخدامه من خلالها. ويمكنك أيضًا إعادة المحاولة لاحقًا.
  • الفاتورة تختلف عن سعر سوق النماذج — تعرض علامة التبويب «الكل» أسعار المجموعة الافتراضية بينما اختار المفتاح مجموعة أخرى؛ أو صادف الطلب أوقات خارج الذروة، أو تجاوزت المطالبة حد السياق الطويل، أو استُخدم البحث على الويب — المعتمد هو المبلغ المفوتر في كل سجل ضمن «الاستخدام والسجلات».
  • ينقطع تطبيق الإنتاج فجأة — حُذف المفتاح أو عُطّل — المفتاح المعطّل يُستعاد بالضغط على «تفعيل» في القائمة؛ أما المحذوف فلا سبيل إلا إنشاء مفتاح جديد واستبدال المفتاح القديم به في التطبيق.

الأسئلة الشائعة

كم يلزم تغييره في الكود للتكامل؟

عادةً موضعان فقط: توجيه base_url إلى البوابة، واستبدال api_key بمفتاح المنصة. البوابة متوافقة مع حزم SDK والبروتوكولات الرسمية، وتبقى بنية الطلب وبنية الرد وتنسيق البث كما هي.

لماذا يختلف المبلغ في الفاتورة عن السعر في سوق النماذج؟

تعرض علامة التبويب «الكل» أسعار المجموعة الافتراضية لكل مزوّد؛ فإذا اختار مفتاحك مجموعة أخرى، يُحتسب السعر وفق تلك المجموعة. كما أن خصم أوقات خارج الذروة، وتغيّر سعر الطلب كله عند تجاوز المطالبة حد السياق الطويل، واحتساب البحث على الويب لكل عملية بحث على حدة، كلها تجعل تكلفة الاستدعاء الواحد تختلف عن السعر المعروض. المعتمد هو المبلغ المفوتر في كل سجل ضمن «الاستخدام والسجلات».

كيف أتحكم في إنفاق مشروع معيّن؟

أنشئ مفتاحًا خاصًا بذلك المشروع، واضبط له حد إنفاق شهري. يُحتسب الحد لكل مفتاح، فلا تتأثر المشاريع ببعضها؛ وإذا أردت تعديله لاحقًا فاضغط «تغيير الحد» في قائمة المفاتيح (يتطلّب التحقق من هويتك).

صفحات ذات صلة: مركز المساعدة · أدلة وأسئلة شائعة · خدمات الذكاء الاصطناعي · وثائق الواجهة البرمجية

جارٍ التحميل…