لا يتطلب ربط OpenAI API سوى أربعة عناصر: حساب يمكن تسجيل الدخول إليه، ومفتاح API صالح، ومشروع مفعّل للفوترة، وعنوان Base URL صحيح مع استدعاء ناجح واحد. يبدو الأمر بسيطًا، لكن ما يعيق الفرق الجديدة عادةً ليس الكود، بل بنية الحساب وطرق الدفع وتركيب العنوان.
تسير هذه المقالة وفق ترتيب العمل الفعلي: الحساب والمشروع، وإنشاء المفتاح، والشحن، وتثبيت SDK، وتنفيذ أول استدعاء عبر Responses API، ومراجعة الاستخدام، وتشخيص الخطأين 401 و429، ثم شرح كيفية تحويل Base URL إلى بوابة متوافقة مع OpenAI. تعتمد الأمثلة هنا على Responses API أساسًا؛ أما الأدوات القديمة التي تدعم Chat Completions فقط فيمكن تكييفها بالطريقة نفسها.
ملاحظة: OpenAI وChatGPT وGPT علامات تجارية مملوكة لشركة OpenAI. تعتمد هذه المقالة على سلوك الواجهات العامة في أكتوبر 2026، وتُراجع أسماء الطرازات والحصص والأسعار وفق صفحة الأسعار والوثائق الرسمية.
أولًا: ما الفرق بين الحساب والمؤسسة والمشروع؟
تضم منصة OpenAI ثلاث طبقات على الأقل، والخلط بينها هو المصدر الأكثر شيوعًا للأخطاء:
- الحساب: بيانات تسجيل الدخول، وهو ما يحدد من يستطيع الوصول إلى لوحة التحكم؛
- المؤسسة: الوحدة التي تُنسب إليها الفوترة والاستخدام، ويُدار التعاون داخل الفريق عادةً على مستواها؛
- المشروع: وحدة عزل المفاتيح والاستخدام والصلاحيات، ويُفضّل تقسيمه حسب البيئة أو النشاط التجاري.
من المفاهيم الخاطئة الشائعة اعتبار اشتراك ChatGPT رصيدًا لواجهة API. الاثنان منفصلان: الاشتراك يمنح حق استخدام منتج المحادثة، بينما تُحاسب واجهة API على الاستدعاءات الفعلية بشكل منفصل. قبل البدء، يتعين على الفريق تحديد من يتولى الحساب، ومن يتولى الدفع، ومن يحمل صلاحيات المسؤول، حتى لا تتعذر معرفة مالك المفتاح عند تغيّر الموظفين لاحقًا.
ثانيًا: ترتيب إنشاء مفتاح API
اتبع الخطوات التالية دون تخطي أي منها:
- سجّل الدخول إلى لوحة تحكم API بحساب مسؤول، وتأكد من أن المؤسسة الحالية صحيحة.
- أنشئ مشروعًا جديدًا تحت المؤسسة أو اختر مشروعًا قائمًا، وافصل بين «التطوير» و«الاختبار» و«الإنتاج».
- انتقل إلى صفحة API Keys داخل المشروع، ثم أنشئ مفتاحًا جديدًا.
- امنح المفتاح اسمًا يوضح الغرض منه، مثل «الإنتاج - روبوت خدمة العملاء».
- انسخ المفتاح الكامل فورًا واحفظه في مدير كلمات المرور أو في إدارة الأسرار على منصة النشر.
- اضبط صلاحيات المشروع أو الميزانية أو سقف الحصة حسب الحاجة، ثم احفظ.
يُعرض المفتاح الكامل عادةً مرة واحدة فقط عند الإنشاء. من الطبيعي أن تظهر بعد ذلك الأحرف الأولى والأخيرة فقط، فلا تعتمد على إمكانية نسخه لاحقًا. إذا فُقد المفتاح، فأنشئ مفتاحًا جديدًا وعطّل القديم، بدلًا من محاولة استعادته.
ثالثًا: الشحن والفوترة والحصص
تعتمد واجهة API على الدفع المسبق أو اللاحق بحسب نوع الحساب والمنطقة، ويُرجح الرجوع إلى ما تعرضه لوحة التحكم. قبل التفعيل، راجع ثلاثة أمور:
- هل تدعم طريقة الدفع بطاقتك أو قناتك المتاحة؟
- كيف تُحتسب دورة الفوترة وكيف تُستخرج الفواتير؟
- هل يمكن ضبط تنبيهات الميزانية وسقف صارم لكل مشروع؟
فشل الدفع من المشكلات المتكررة في مرحلة الربط. عند رفض البطاقة، تحقق أولًا من عنوان الفوترة واسم حامل البطاقة وطريقة التحقق، ثم تواصل مع البنك المُصدر؛ لا تكرر الإرسال خلال فترة قصيرة، لأن بعض أنظمة مكافحة المخاطر قد تحظر العملية بسبب ذلك. تستطيع الفرق التي تعتمد بوابة API الشحن بالعملة المحلية عادةً، وتُراجع الأسعار وقواعد الوصول إلى الرصيد في صفحة الأسعار، مع العلم بأن الأسعار قابلة للتعديل وأن ما تعرضه الصفحة وقت الطلب هو المرجع.
رابعًا: تثبيت SDK وإرسال أول طلب curl
ابدأ بتثبيت حزمة Python الرسمية:
python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-مفتاحك"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="اسم الطراز المنسوخ من صفحة الأسعار أو الوثائق الرسمية"
استخدم curl لاستدعاء Responses API والتأكد من سلامة العنوان والمفتاح والشبكة:
curl -sS "$OPENAI_BASE_URL/responses" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$OPENAI_MODEL"'",
"input": "اشرح في جملة واحدة ما هي بوابة API."
}'
لا تكتب اسم الطراز من الذاكرة؛ انسخ الاسم المتاح حاليًا من صفحة الأسعار أو الوثائق الرسمية واحفظه في المتغير OPENAI_MODEL. إذا عاد الطلب بالرمز 200 وتضمن الجسم مخرجات، فالمسار يعمل. إذا عاد بالرمز 401 فراجع المفتاح أولًا، وإذا عاد بالرمز 404 فراجع Base URL واسم الطراز.
خامسًا: أول استدعاء بلغة Python
يرسل المثال التالي طلبًا بسيطًا عبر Responses API ويطبع النص الناتج:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["OPENAI_API_KEY"],
base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)
resp = client.responses.create(
model=os.environ["OPENAI_MODEL"],
input="عرّف حدود قدراتك في ثلاث جمل.",
)
print(resp.output_text)
إذا كان إطار العمل لديك يدعم Chat Completions فقط، فاستبدل الاستدعاء بـ client.chat.completions.create(...) وضع الرسائل في messages. تختلف مسارات الطلب بين الواجهتين، والخلط بينهما هو السبب الأكثر شيوعًا لخطأ 404.
سادسًا: فهم الاستخدام والفاتورة
تعرض صفحة Usage في لوحة التحكم عادةً الاستهلاك وفق ثلاثة أبعاد: المشروع والطراز والزمن، مع التمييز بين الإدخال والإخراج. في المرحلة الأولى من الربط، يُنصح بمراجعتها يوميًا والتركيز على:
- أي مشروع يستهلك الحصة؛
- ما نسبة الإدخال إلى الإخراج؛
- هل توجد إعادة محاولات فاشلة غير طبيعية؛
- هل تنبيهات الميزانية تعمل فعليًا.
احفظ معرّف الطلب (Request ID) العائد مع كل استدعاء في السجلات. عند نشوء خلاف حول الفوترة أو حدوث عطل، يكون معرّف الطلب أول مادة يستخدمها مزوّد الخدمة لتحديد المشكلة. كذلك ينبغي أن يسجل التطبيق العلاقة بين المستخدم ووحدة الوظيفة ومعرّف الطلب، وإلا فلن تُظهر الفاتورة سوى الإجمالي دون إمكانية إرجاع التكلفة إلى مصدرها.
سابعًا: كيفية تشخيص الخطأين 401 و429
يعني الخطأ 401 أن الهوية غير مقبولة. تحقق بالترتيب من: وجود Bearer في ترويسة الطلب؛ عدم وجود مسافات أو أسطر جديدة زائدة في المفتاح؛ عدم حذف المفتاح أو تعطيل المشروع التابع له؛ وعدم إرسال مفتاح البوابة إلى العنوان الرسمي. قبل تغيير المفتاح، تأكد من الوجهة الفعلية للطلب، وإلا فقد يذهب الجهد سدى.
للخطأ 429 معنيان: تجاوز حد المعدل، أو عدم كفاية الرصيد. اقرأ رمز الخطأ وترويسات الاستجابة بدلًا من خفض السرعة تلقائيًا. يشير insufficient_quota عادةً إلى الرصيد أو الحصة، ويستلزم الشحن أو تعديل سقف المشروع؛ أما أخطاء المعدل فهي وحدها التي تناسب التراجع الأسي. لا جدوى من إعادة المحاولة إلا مع 429 و5xx وأخطاء الشبكة؛ أما 400 و401 و403 و404 فإعادة المحاولة معها تهدر الحصة فقط. سجّل كل محاولة ومعرّف الطلب الخاص بها لتتبّع أسباب الأخطاء، ويمكن مراجعة الخطط والأسعار في صفحة الأسعار.
ثامنًا: الاتصال المباشر الرسمي أم البوابة المتوافقة؟
| البُعد | الاتصال المباشر الرسمي | بوابة متوافقة مع OpenAI |
|---|---|---|
| عنوان الاتصال | https://api.openai.com/v1 |
Base URL تقدمه البوابة، وينتهي عادةً أيضًا بـ /v1 |
| الحساب والدفع | حساب رسمي، وفق طرق الدفع التي يدعمها المزود | حساب داخل البوابة، مع إمكانية الشحن بالعملة المحلية وإصدار الفواتير |
| الشبكة | تعتمد على الشبكة المحلية والمسار العابر للحدود | توفر عادةً نقطة وصول متاحة محليًا |
| نطاق الطرازات | طرازات OpenAI فقط | قد تجمع طرازات من عدة مزودين، وفق صفحة الأسعار |
| الفوترة | فاتورة رسمية | رصيد وسجلات استخدام داخل البوابة |
| معالجة الأعطال | عبر قنوات الدعم الرسمية | تتولى البوابة تشخيص المصدر الأعلى، ويحتفظ المستخدم بمعرّف الطلب |
| الحالات المناسبة | فرق تستخدم OpenAI وحدها ولديها مسار دفع متوافق | فرق محلية تحتاج عدة طرازات وفاتورة موحدة |
لا تقارن السعر الاسمي وحده عند الاختيار. فسهولة الدفع، ومن يتولى معالجة الأعطال، وإمكانية تبديل الطراز في أي وقت، كلها تؤثر في التكلفة طويلة الأمد. الأسعار متغيرة، والمرجع دائمًا هو صفحة الأسعار.
تاسعًا: الانتقال إلى بوابة متوافقة: تغيير Base URL فقط
غالبًا ما تكون تكلفة الانتقال أقل مما يُتوقع، لأن البوابة المتوافقة تحافظ على صيغة الطلب نفسها. ترتيب الخطوات:
- سجّل في البوابة وأنشئ مفتاحًا من صفحة التسجيل.
- غيّر
OPENAI_BASE_URLإلى عنوان البوابة مع الإبقاء على/v1. - استبدل المفتاح بمفتاح البوابة، ولا تخلط بين مجموعتي المفاتيح.
- انسخ اسم الطراز من صفحة أسعار البوابة، ولا تعتمد على الاسم الرسمي على سبيل التجربة.
- اختبر أولًا
/v1/modelsوطلبًا بسيطًا، ثم انقل حركة الإنتاج. - احتفظ بالخط الرسمي أو بخط بديل كخيار احتياطي.
تعني عبارة «متوافق مع OpenAI» أن صيغتي الطلب والاستجابة متوافقتان، ولا تعني بالضرورة تطابق جميع القدرات الإضافية. يجب التحقق من دعم الملفات والدفعات الدفعية واستدعاء الأدوات وغيرها من الواجهات المتقدمة بندًا بندًا في وثائق البوابة، دون افتراض توفرها جميعًا. ويمكن مراجعة نطاق الخيارات والأسعار في صفحة الأسعار قبل اعتماد الانتقال.
عاشرًا: أمان المفتاح وقائمة التحقق قبل الإطلاق
تسريب المفتاح يؤدي إلى تكاليف مباشرة. الحد الأدنى المطلوب:
- لا يوضع المفتاح إلا في متغيرات بيئة الخادم أو خدمة إدارة الأسرار، ولا يُكتب في كود الواجهة الأمامية ولا يُرفع إلى Git؛
- يُفصل المفتاح حسب البيئة، فلا يُشترك بين الاختبار والإنتاج؛
- يُوثق لكل مفتاح المسؤول والغرض، ويُعطّل فورًا عند مغادرة الموظف أو تغيّر المشروع؛
- لا يُطبع المفتاح كاملًا في السجلات، بل آخر أربعة أحرف فقط؛
- يُستبدل المفتاح دوريًا، ويُلغى فورًا عند رصد استدعاءات غير طبيعية.
تحقق من البنود التالية قبل الإطلاق:
- [ ] الحساب والمؤسسة والمشروع واضحة الملكية؛
- [ ] طريقة الدفع تعمل، وتنبيهات الميزانية مضبوطة؛
- [ ] المفتاح محفوظ في متغيرات البيئة أو إدارة الأسرار؛
- [ ] Base URL يحتوي على
/v1مرة واحدة فقط؛ - [ ] الطلب البسيط يعيد 200 ومحتوى سليمًا؛
- [ ] التراجع عند 429 وإعادة المحاولة عند 5xx مهيّآن؛
- [ ] سجلات الاستخدام تتضمن معرّف الطلب والطراز وزمن الاستجابة؛
- [ ] جُرّب مسار الخط البديل وإجراء تعطيل المفتاح.
حادي عشر: الأسئلة الشائعة
هل مفتاح API واشتراك ChatGPT شيء واحد؟
لا. يُحاسب الاشتراك وواجهة API بشكل منفصل، ويُنشأ مفتاح API ويُدار داخل منصة API فقط. عند تسوية نفقات الفريق يجب التمييز بين البندين.
لماذا لا يظهر المفتاح الكامل بعد إنشائه؟
يُعرض المفتاح الكامل عادةً مرة واحدة عند الإنشاء، وتحتفظ المنصة بجزء من الأحرف للتعريف فقط. إذا فُقد، فأنشئ مفتاحًا جديدًا وعطّل القديم.
إلى أي حد يُكتب Base URL؟
يُكتب حتى اسم النطاق مضافًا إليه /v1، دون /chat/completions أو /responses. يتولى SDK أو الطلب نفسه تركيب المسار، وأي جزء إضافي يؤدي إلى 404.
هل يمكن استخدام مفتاح واحد لعدة مشاريع؟
تقنيًا نعم، لكنه غير مستحسن إداريًا. تقسيم المفاتيح حسب المشروع أو البيئة يتيح ضبط الصلاحيات وتحديد الاستهلاك وتقليص أثر أي تسريب.
هل تحتاج الفرق المحلية إلى بوابة بالضرورة؟
ليس بالضرورة. يعتمد القرار على قنوات الدفع وجودة الشبكة ومتطلبات الامتثال والحاجة إلى عدة طرازات. الفرق التي تستخدم OpenAI وحدها ولديها دفع وشبكة مستقران يمكنها الاتصال المباشر؛ أما الفرق التي تحتاج تسوية محلية ونقطة دخول موحدة فيمكنها تقييم الانتقال عبر صفحة الأسعار.
الخطوة التالية
شغّل الطلب البسيط أولًا، ثم اربط أعمالك. إذا كنت تحتاج إلى الشحن المحلي ونقطة دخول موحدة لعدة طرازات، فابدأ من التسجيل في بوابة ZSQH AI؛ أما الطرازات والأسعار فهي وفق صفحة الأسعار.
قراءات ذات صلة:
