ChatGPT API – الدليل التقني الشامل للمطورين

شهدت واجهة OpenAI API تطورًا كبيرًا في السنوات الأخيرة، مما أتاح للمطورين دمج نماذج الذكاء الاصطناعي المتقدمة داخل تطبيقاتهم وأنظمتهم بصورة أكثر مرونة وكفاءة. ورغم شيوع مصطلح ChatGPT API في البحث والتداول، فإن التوصيف الأدق تقنيًا للمشاريع الجديدة اليوم هو OpenAI API، وبشكل خاص Responses API. تتيح هذه الواجهة للتطبيقات الاتصال برمجيًا بنماذج OpenAI المتاحة عبر منصة المطورين لتنفيذ مهام مثل المحادثة، والتلخيص، والشرح، وتوليد الأكواد، والترجمة، وغيرها. ومن المهم التفريق هنا بين ChatGPT كمنتج موجّه للمستخدم النهائي وبين OpenAI API كمنصة مستقلة للمطورين؛ فهناك تقاطع في القدرات العامة، لكن النماذج المتاحة، وحدود الاستخدام، وآلية الفوترة ليست بالضرورة متطابقة بينهما.

في هذه المقالة التقنية المتعمقة، سنقدم تعريفًا دقيقًا لماهية Responses API وأهميتها، ثم نستعرض الفرق بين استخدام نموذج ChatGPT عبر الموقع أو التطبيق العادي وبين استخدامه عبر API. سنتطرق أيضًا إلى شرح آلية عمل هذه الواجهة وكيفية إرسال الطلبات ومعالجة الاستجابات، بالإضافة إلى خطوات الحصول على مفتاح API خاص بك. سنقدم أمثلة عملية كاملة بلغتي برمجة شائعتين (Python وNode.js) توضح كيفية دمج Responses API في المشاريع البرمجية باستخدام أحدث إصدارات الـSDK المتاحة. بعد ذلك، سنشرح أهم المتغيرات والبارامترات في طلبات الـAPI (مثل model وinput وmax_output_tokens)، بالإضافة إلى شرح آلية التسعير مع أمثلة سعرية مرتبطة بصفحة التسعير الرسمية لـ OpenAI API، لأن الأسعار قد تتغير بمرور الوقت.

ومن المهم أيضًا توضيح جانب البيانات والخصوصية منذ البداية: فبحسب وثائق OpenAI الحالية، لا تُستخدم البيانات المرسلة إلى OpenAI API لتدريب أو تحسين النماذج افتراضيًا منذ 1 مارس 2023، إلا إذا اختار العميل صراحةً مشاركة بياناته لهذا الغرض. ومع ذلك، قد تُنشأ سجلات مراقبة إساءة الاستخدام وتُحتفظ افتراضيًا لمدة تصل إلى 30 يومًا، كما قد تحتفظ بعض الميزات ببيانات تشغيلية لازمة لتنفيذ الطلب أو استمرار الجلسة، وهو ما يختلف عن استخدام البيانات في تدريب النماذج.

لن نغفل أيضًا أفضل الممارسات الأمنية لحماية مفاتيح API والبيانات الحساسة، وكذلك كيفية التعامل مع معدلات الاستخدام (Rate Limits) وأخطاء الـAPI الشائعة وسبل معالجتها بشكل صحيح. وأخيرًا، سنختتم بخاتمة تقنية احترافية تلخص ما تم تناوله، يتلوها قسم الأسئلة الشائعة(FAQ) للإجابة عن أبرز الاستفسارات حول Responses API.

دعونا نبدأ بفهم ماهية Responses API ولماذا أصبحت إحدى أهم أدوات المطورين في مجال الذكاء الاصطناعي.

ما هو Responses API؟

Responses API هي خدمة ضمن OpenAI API تُمكّن المطورين من إرسال المدخلات إلى نماذج OpenAI واستقبال استجابات برمجية يمكن دمجها مباشرة داخل التطبيقات. وبعبارة عملية، فهي تمنحك وصولًا مباشرًا إلى قدرات النماذج عبر الـAPI لبناء محادثات، وتلخيصات، وعمليات توليد محتوى أو كود، من دون الاعتماد على واجهة ChatGPT نفسها. لذلك من الأدق القول إن الـAPI توفّر قدرات قد تتقاطع مع ما يختبره المستخدم داخل ChatGPT في كثير من الحالات، لا أنها تتيح دائمًا نفس النماذج أو نفس تجربة المنتج حرفيًا.

أُطلقت Responses API رسميًا في مارس 2025 كواجهة حديثة ضمن OpenAI API، وتهدف إلى توفير طريقة أبسط وأكثر مرونة لبناء التطبيقات الذكية والوكلاء البرمجيين باستخدام نماذج OpenAI. وقد قدّمت OpenAI هذه الواجهة باعتبارها امتدادًا يجمع بين بساطة Chat Completions API وقدرات الأدوات وإدارة الحالة التي عُرفت في Assistants API. أما سياق عام 2023، فهو يرتبط بطرح واجهات أقدم مثل GPT‑3.5 Turbo API — التي كان يُشار إليها آنذاك باسم ChatGPT API — وليس بإطلاق Responses API نفسها. كانت Assistants API تمثل سابقًا مسارًا لبناء مساعدين ذوي حالة وأدوات، لكن OpenAI أعلنت إيقافها تدريجيًا، مع موعد إيقاف نهائي في 26 أغسطس 2026، وتوصي الآن باستخدام Responses API مع Conversations API بدلًا منها في المشاريع الجديدة. ومع تطور المنصة لاحقًا، أصبحت Responses API الواجهة الموصى بها للمشاريع الجديدة، مع استمرار دعم Chat Completions API للتكاملات القائمة.

بشكل أساسي، تعمل Responses API عبر نقطة نهاية HTTP توفرها OpenAI. يرسل التطبيق طلب HTTP (عادةً من نوع POST) إلى خادم OpenAI، يتضمن الطلب معلومات مثل النموذج المطلوب استخدامه والمدخلات النصية (سواء سؤال أو محادثة سابقة)، ويقوم خادم OpenAI بمعالجة المدخلات باستخدام النموذج اللغوي، ثم يُرجع استجابة على شكل JSON تحتوي على النص المُولد من قبل الذكاء الاصطناعي. هذا يسمح للمطور بقراءة الاستجابة وعرضها للمستخدم أو استخدامها حسب الحاجة داخل التطبيق.

من المهم التمييز بين Responses API وChat Completions API بدل التعامل معهما على أنهما الشيء نفسه. Responses API هي الواجهة الحديثة ضمن OpenAI API، وتوصي بها OpenAI للمشاريع الجديدة، وهي تمثل تطورًا لواجهة Chat Completions مع بنية أبسط وقدرات إضافية مثل الأدوات المدمجة، والتفاعلات متعددة الخطوات، ودعم أفضل للتطبيقات الحديثة. أما Chat Completions API فما تزال مدعومة، لكنها واجهة أقدم تُستخدم أساسًا للتكاملات القائمة أو للحالات التي لا تحتاج إلى قدرات Responses الأحدث. لذلك فالأدق في هذا المقال هو اعتبار Responses API واجهة أحدث وأوسع من Chat Completions API، لا مجرد اسم آخر لها.

الفرق بين ChatGPT عبر الواجهة العادية وعبر API

يخلط البعض بين استخدام ChatGPT من خلال الموقع أو التطبيق الرسمي، وبين استخدامه عبر واجهة الـAPI في التطبيقات. هناك فروقات جوهرية ينبغي فهمها:

• طريقة الوصول والتفاعل: عند استخدام ChatGPT عبر الموقع (أو تطبيق الهاتف)، يتم التفاعل من خلال واجهة مستخدم (UI) توفرها OpenAI. أنت تكتب سؤالك في صندوق الدردشة وتحصل على الإجابة في المقابل. أما عبر API، فلا وجود لواجهة مستخدم جاهزة – بدلاً من ذلك، يتولى تطبيقك أنت مسؤولية إرسال الأسئلة واستقبال الإجابات برمجيًا وعرضها بالطريقة التي تناسب تطبيقك. بكلمات أخرى، Responses API هي للواجهات الخلفية (Back-end) حيث يتولى المطور تصميم واجهة الاستخدام النهائية للمستخدمين.
• الحفاظ على سياق المحادثة: في موقع ChatGPT العادي، يتم تذكر سياق المحادثة تلقائيًا؛ فبإمكانك متابعة الحوار وسيفهم ChatGPT ما تم ذكره سابقًا. عند استخدام الـAPI، يجب على التطبيق تمرير سجل المحادثة السابق ضمن كل طلب إذا كان يريد من النموذج تذكر السياق. سابقًا كان ذلك يتم عبر إرسال قائمة الرسائل (messages) بما يشمل أدوار كل رسالة (مستخدم أو مساعد أو نظام). اليوم توجد عدة طرق لإدارة سياق المحادثة عند استخدام Responses API، مثل إدارة السجل يدويًا داخل التطبيق، أو ربط الردود عبر previous_response_id، أو استخدام Conversations API لحفظ المحادثة عبر الجلسات. وبالنسبة للمحادثات الطويلة أو متعددة الجلسات، يُعد Conversations API خيارًا عمليًا لأنه يقلل الحاجة إلى إعادة إرسال السجل كاملًا في كل مرة، مع بقاء خيار الإدارة اليدوية متاحًا عند الحاجة. بالمحصلة، عبر الـAPI لديك مرونة أعلى: يمكنك بناء تجربة محادثة بسيطة من سؤال وجواب بدون سياق، أو تجربة تفاعلية متقدمة تحتفظ بسياق طويل عبر عدة رسائل بحسب احتياج تطبيقك.
• التخصيص والتحكم: استخدام ChatGPT عبر الـAPI يمنحك تحكمًا كاملاً في كيفية توظيف النموذج. يمكنك على سبيل المثال تغيير نغمة المساعد عبر تمرير تعليمات خاصة في دور “system” (مثلاً: اجعل أسلوبك تقنيًا وموجزًا)، أو تحديد معلمات التوليد كتغيير درجة العشوائية (temperature) لجعل الإجابات أكثر إبداعًا أو أكثر تحفظًا. في واجهة ChatGPT العادية، هذه الخيارات محدودة للمستخدم النهائي (هناك بعض الإعدادات مثل درجة الإبداع في بعض الإصدارات، ولكن ليس بالتفصيل المتاح في الـAPI). كما يمكنك عبر الـAPI دمج قدرات النموذج مع بياناتك الخاصة أو أدواتك الخاصة – فمثلاً يمكن للتطبيق استدعاء Responses API ثم إجراء معالجة إضافية على النتيجة قبل عرضها.
• التكلفة والفوترة: الوصول إلى ChatGPT عبر الموقع أو التطبيق يكون من خلال خطط اشتراك موجهة للمستخدم النهائي، أما OpenAI API فتعمل وفق نموذج الدفع حسب الاستخدام بناءً على عدد التوكنات المستهلكة. والاشتراك في ChatGPT Plus أو غيره من خطط ChatGPT لا يعني تلقائيًا أن استخدام الـAPI مشمول ضمنه، لأن منصة ChatGPT ومنصة API تُداران وتُحاسبان بشكل منفصل. لهذا السبب، من الأدق في المقال الفصل بوضوح بين تكلفة ChatGPT كمنتج استهلاكي وتكلفة OpenAI API كخدمة للمطورين.
• القيود وسياسات الاستخدام: قد يلاحظ المستخدم أن واجهة ChatGPT أحيانًا ترفض بعض المدخلات المخالفة لسياسات المحتوى أو تفرض حدودًا على عدد الرسائل حسب نوع الحساب. عند استخدام OpenAI API يظل النموذج ملتزمًا بسياسات المحتوى نفسها، لكن يمتلك المطور مرونة أكبر في كيفية استخدام المخرجات داخل التطبيق، مثل معالجتها أو تعديلها قبل عرضها للمستخدم. كما تعتمد الـAPI نظام حدود معدل الاستخدام (Rate Limits) يختلف عن واجهة ChatGPT، حيث تُدار هذه الحدود عادةً على مستوى المنظمة أو المشروع وليس المستخدم فقط، وقد تُعرض بصيغ مثل RPM وTPM وRPD وTPD بحسب النموذج ونوع الاستخدام. باختصار، تمنح الـAPI مرونة أكبر للمطورين، لكنها تتطلب أيضًا الالتزام بسياسات الاستخدام وتأمين مفاتيح الـAPI وإدارة التكلفة بشكل صحيح.
• توافر النماذج والمنصة: لا ينبغي افتراض أن كل نموذج يظهر داخل ChatGPT سيكون متاحًا بالاسم نفسه أو في الوقت نفسه عبر الـAPI، أو العكس. توضح OpenAI أن ChatGPT platform وAPI platform منصتان منفصلتان، كما أن بعض تغييرات النماذج داخل ChatGPT لا تؤثر بالضرورة في الوصول عبر الـAPI. قد تختلف النماذج المتاحة وتوقيتات الإطلاق أو الإيقاف بين ChatGPT وAPI؛ فعلى سبيل المثال، قد تتغير تشكيلة النماذج في ChatGPT بينما تستمر نماذج أخرى داخل الـAPI لفترة أطول. لذلك عند الشرح التقني، الأفضل الحديث عن تقاطع في القدرات بين ChatGPT وOpenAI API، بدل وصفهما بأنهما يستخدمان دائمًا نفس النماذج حرفيًا.

باختصار، ChatGPT UI موجه للمستخدم النهائي لتجربة جاهزة وسهلة، بينما Responses API موجهة للمطورين لدمج قدرات ChatGPT في أنظمتهم مع حرية التخصيص والتحكم الكامل في التجربة.

كيف تعمل Responses API؟ (آلية العمل)

لفهم آلية عمل Responses API تقنيًا، لنستعرض الخطوات التي تحدث عند إرسال طلب API نموذجية:

تكوين طلب HTTP: يستخدم التطبيق (العميل) بروتوكول HTTPS للاتصال بخادم واجهة OpenAI. عنوان الواجهة (Endpoint) الرئيسي لخدمة الدردشة هو عادة:
https://api.openai.com/v1/chat/completions
أو في الواجهة الأحدث:
https://api.openai.com/v1/responses
على حسب الصيغة المستخدمة. في كلا الحالتين، يجب تضمين مفتاح API السري في ترويسات الطلب لأغراض المصادقة (عادة في حقل Authorization بالشكل: Bearer YOUR_API_KEY).

هيكلية البيانات المرسلة: يتم إرسال البيانات عادة بصيغة JSON في جسم الطلب (HTTP request body). عند استخدام Chat Completions API التقليدية، تكون البيانات المرسلة كالتالي مثلًا:

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "أنت مساعد مفيد."},
    {"role": "user", "content": "ما هي مهمة Responses API؟"}
  ],
  "max_tokens": 100
}

هنا حقل model يحدد نموذج الذكاء الاصطناعي (مثلاً gpt-4o-mini أو gpt-4o). حقل messages يتضمن تسلسل الرسائل في المحادثة مع تحديد دور كل رسالة (system للرسائل التوجيهية، user لرسائل المستخدم، assistant لردود النموذج السابقة إن وُجدت). في هذا المثال تم إعطاء رسالة نظام تطلب من النموذج أن يكون مساعدًا مفيدًا، ثم رسالة مستخدم بسؤال. أخيرًا يحدد max_tokens الحد الأقصى لعدد الرموز التي يمكن للنموذج توليدها في الاستجابة (هنا 100 رمز كحد أقصى). مع واجهة Responses API الأحدث، أصبح بالإمكان استخدام بناء أبسط للطلبات في كثير من الحالات، مثل:

{
  "model": "gpt-4o",
  "input": "ما هي مهمة Responses API؟",
  "instructions": "أنت مساعد مفيد.",
  "max_output_tokens": 100
}

نلاحظ هنا استخدام حقل input منفرد للنص المدخل بدلًا من قائمة messages، ويمكن إعطاء تعليمات عامة في حقل instructions (تعادل دور system في المثال السابق). حقل max_output_tokens يؤدي نفس الغرض الذي يؤديه max_tokens، ولكن واجهة Responses API تعتمد التسمية الجديدة max_output_tokens لضبط الحد الأعلى لطول الإجابة. في كلتا الحالتين، النتيجة واحدة: سيستخدم النموذج هذه المعلومات لتوليد الرد.

معالجة الطلب على الخادم: عند استلام خادم OpenAI للطلب والتحقق من صحة مفتاح API والصلاحيات، يقوم بتوجيه المدخلات إلى النموذج المطلوب. النموذج (وهو شبكة عصبونية ضخمة مدربة على فهم اللغات الطبيعية) يقوم بمعالجة التوكنات المدخلة وتوليد استجابة بناءً على المعرفة المكتسبة خلال تدريبه. يجدر الذكر أن النموذج يتعامل مع النصوص كسلسلة من الوحدات أو التوكنات (token) وليس الحروف المفردة – والتوكن قد يكون كلمة أو جزء من كلمة. سيأخذ النموذج في الحسبان كل الرسائل السابقة وتعليمات النظام المقدمة عند توليد الرد، خاصة في حالة المحادثات المتعددة الأدوار.

إعادة الاستجابة (Response): يُرسِل الخادم استجابة HTTP تحتوي على بيانات JSON. في حالة نجاح الطلب، عادةً ما يكون شكل الاستجابة (لواجهة Chat Completions) مشابهًا للتالي:

{
  "id": "chatcmpl-abc123...",
  "object": "chat.completion",
  "created": 1690000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "واجهة Responses API هي خدمة توفرها OpenAI للمطورين..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 30,
    "total_tokens": 50
  }
}

هنا نرى أن الاستجابة تتضمن معرفًا فريدًا للطلب (id)، والطابع الزمني، بالإضافة إلى النموذج المستخدم. تحت choices نجد قائمة بالردود المحتملة (في حال طلبت أكثر من رد عبر parâmetro مثل n، لكن بشكل افتراضي يكون عنصر واحد). يحتوي كل خيار على الرسالة التي ولدها المساعد (role: assistant والمحتوى). finish_reason تشير لسبب انتهاء التوليد (هنا “stop” يعني أن النموذج انتهى من الرد دون انقطاع). أيضًا قسم usage يعطينا إحصاءات عدد الرموز المستخدمة في الطلب (المدخلات) وعدد الرموز في التكملة (الإجابة) وإجماليها. هذه المعلومات مهمة لحساب التكلفة. في الاستجابة الخام لـResponses API، البنية الأساسية تعتمد على output وما بداخله من عناصر typed items. أمّا output_text فهو خاصية مساعدة في SDKs الخاصة ببايثون وجافاسكريبت لتجميع النص النهائي بسهولة، وليس الحقل الخام الأساسي الذي يجب أن تشرح به REST response.

استخدام الاستجابة في التطبيق: الآن يأتي دور التطبيق لاستلام هذه الـJSON واستخدامها. مثلاً يمكنه استخراج content من الرسالة وإظهارها للمستخدم في واجهة الدردشة الخاصة بتطبيقك. أو ربما إذا كنت تطلب من OpenAI API توليد كود برمجي، فسيقوم التطبيق بتضمين هذا الكود في صفحة أو تنفيذ خطوات بناءً عليه. عمليًا، المطور يتحكم كليًا في كيفية الاستفادة من مخرجات الـAPI – يمكنك حتى عدم إظهار الرد كاملاً للمستخدم وإجراء تعديلات عليه، أو دمج عدة ردود من طلبات مختلفة، إلخ.

من النقاط المهمة في آلية العمل الحديثة لـOpenAI API عبر Responses API أنه يمكن للمطور استخدام آليات ربط الاستجابات أو بعض ميزات التخزين التشغيلي للحفاظ على سياق المحادثة بدل إعادة إرسال السجل كاملًا في كل مرة. ويجدر هنا التمييز بين تخزين الحالة التشغيلية (Application State) اللازمة لتنفيذ الطلب أو استمرار الجلسة، وبين استخدام البيانات لتدريب النماذج؛ فبحسب سياسة OpenAI الحالية، لا تُستخدم البيانات المرسلة إلى OpenAI API لتدريب أو تحسين النماذج افتراضيًا، إلا إذا اختار العميل صراحةً مشاركة البيانات لهذا الغرض. أما سجلات مراقبة إساءة الاستخدام فقد تُنشأ افتراضيًا وتُحتفظ لمدة تصل إلى 30 يومًا، ما لم تنطبق ضوابط احتفاظ خاصة أو متطلبات قانونية مختلفة.

أيضًا، يدعم Responses API أسلوب البث (Streaming) في الاستجابة عند الطلب، بحيث يمكنك استقبال أجزاء الإجابة تباعًا وعرضها بشكل لحظي للمستخدم بدل الانتظار حتى يكتمل الجواب. لكن استخدام البث يحتاج إعداد خاص (مثلاً تمرير stream=true ومتابعة استلام تدفق البيانات). في هذا المقال سنركز على الأساسيات ونستعرض الاستجابات غير المتدفقة لسهولة الفهم.

الآن وبعد فهم الآلية، دعونا نتعرف على كيفية الحصول على مفتاح API لاستخدام الخدمة، ثم ننتقل إلى الأمثلة العملية.

كيفية الحصول على مفتاح OpenAI API Key

تُدار مفاتيح الـAPI اليوم من خلال لوحة التحكم ضمن إعدادات المنظمة/المشروع. ويمكن إنشاء Personal keys أو Service account keys على مستوى المشروع، مع مستويات أذونات مثل All / Restricted / Read Only. لهذا فمن الأدق الحديث عن مفاتيح مرتبطة بالـorganization/project وليس فقط بالحساب بصياغة مبسطة قديمة. هذا المفتاح هو بمثابة كلمة المرور التي تتيح لتطبيقك استخدام واجهات OpenAI بالنيابة عنك، لذا يجب التعامل معه بحذر وعدم مشاركته. إليك خطوات الحصول على مفتاح API:

1. إنشاء حساب مطور OpenAI: إذا كان لديك حساب في ChatGPT، فيمكنك استخدام نفس بيانات الدخول في منصة المطورين. توجه إلى منصة OpenAI عبر الرابط: platform.openai.com وقم بتسجيل الدخول بحسابك.
2. الوصول إلى صفحة المفاتيح (API Keys): بعد تسجيل الدخول، ابحث عن قائمة الحساب (قد تكون عبارة عن أيقونة ملفك الشخصي في أعلى يمين الصفحة). انقر عليها ثم اختر خيار “View API keys” أو ما يشابهه للوصول إلى صفحة إدارة مفاتيح الـAPI. بدلاً من ذلك، يمكن زيارة الرابط مباشرة: https://platform.openai.com/account/api-keys.
3. إنشاء مفتاح جديد: في صفحة المفاتيح، ستجد زرًا بعنوان “Create new secret key” (إنشاء مفتاح سري جديد). اضغط عليه. ستظهر نافذة تطلب منك تسمية المفتاح (يمكنك اختيار أي اسم تذكيري مثل “مفتاح مشروعي التجريبي”). بعد إدخال الاسم، اضغط إنشاء.
4. نسخ وحفظ المفتاح: سيتم توليد مفتاح API مكوّن من سلسلة أحرف تبدأ عادة بـ sk- متبوعة بحوالي 48 حرفًا. سيظهر المفتاح لمرة واحدة فقط على الشاشة – قم بنسخه وحفظه في مكان آمن الآن. إذا أغلقت النافذة أو حدث تحديث للصفحة، لن تتمكن من رؤية نفس المفتاح مرة أخرى (وستحتاج لإنشاء مفتاح جديد إن فقدته). يمكنك حفظ المفتاح في ملف آمن على جهازك أو مباشرة في متغير بيئة (Environment Variable) على حاسوبك للمزيد من الأمان (كما سنشرح بعد قليل).
5. ضبط حد الفوترة (اختياري): نظام الفوترة في API يعتمد اليوم على Billing / Usage limits / Tiers بصورة أوضح. يوجد Prepaid Billing بحد شراء أدنى يبدأ من $5، لكن هذا ليس هو نفسه ‘الحد الشهري الافتراضي’. كما أن حدود الاستخدام ترتبط بالـusage tier؛ فالمستخدم الحر في الجغرافيا المدعومة لديه حد استخدام شهري، وTier 1 يبدأ بعد أول دفعة مؤهلة، ثم ترتفع الحدود تلقائيًا مع الوقت والإنفاق. أيضًا، ميزانيات المشاريع Project Budgets هي تنبيهات Soft thresholds وليست قفلًا صلبًا يوقف الاستهلاك تلقائيًا.

الآن أصبح لديك مفتاح API جاهز. لتجربة المفتاح سريعًا، يمكنك استخدام أداة كـPostman أو حتى سطر الأوامر عبر أمر curl لإرسال طلب بسيط للتأكد من أنه يعمل (باستخدام النموذج التجريبي gpt-4o-mini مثلًا). ولكن الطريقة الأفضل هي تضمينه في كود برمجي. ننصحك بعدم وضع المفتاح مباشرة في الكود بشكل نص صريح عند بناء تطبيق حقيقي، بل قراءته من متغير بيئة أو ملف إعدادات غير مشارك في المستودع. مثلًا على نظام لينكس/ماك يمكن فتح الطرفية وإضافة المفتاح:

export OPENAI_API_KEY="sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

وبهذا يصبح المفتاح محفوظًا في متغير البيئة OPENAI_API_KEY ليستخدمه برنامجك. وينطبق الأمر نفسه على Windows مع أوامر setx. معظم مكتبات الـSDK الخاصة بـOpenAI تلقائيًا تقرأ المفتاح من المتغير البيئي إذا لم تحدده أنت في الكود.

تذكّر: مفتاح API خاص وسري. أي شخص يحصل عليه يمكنه استعماله لإرسال طلبات على حسابك (وربما تكبيدك رسومًا)، لذا لا تشاركه علنًا. لاحقًا في قسم الأمان سنذكر بعض أفضل الممارسات لحماية المفاتيح.

بعد أن أصبح المفتاح جاهزًا، لننتقل إلى أمثلة عملية لكيفية استخدام Responses API في الكود.

مثال عملي: استخدام Responses API مع بايثون (Python)

لنبدأ بمثال بلغة بايثون، وهي من أكثر اللغات استخدامًا مع خدمات الذكاء الاصطناعي. وفرت OpenAI مكتبة رسمية للبايثون تسمى OpenAI Python SDK لتسهيل استدعاء الـAPI دون الحاجة إلى بناء طلبات HTTP يدويًا. تأكد أولًا من تثبيت المكتبة (إن لم تكن مثبتة) عبر الأمر:

pip install openai

والآن سنكتب برنامجًا بسيطًا يرسل استفسارًا إلى Responses API ويطبع الإجابة.

مثال: برنامج Python يستدعي Responses API

from openai import OpenAI

# إنشاء عميل OpenAI (سيقرأ المفتاح تلقائيًا من متغير البيئة)
client = OpenAI()

# إرسال طلب إلى Responses API
response = client.responses.create(
    model="gpt-4o-mini",
    input="أهلًا، ما أفضل الممارسات لحماية مفاتيح API؟",
    max_output_tokens=200
)

# طباعة النص الناتج
print(response.output_text)

ما يقوم به هذا الكود: في البداية قمنا باستيراد المكتبة وضبط المفتاح (يفضل كما ذكرنا استخدام متغير بيئة بدل كتابة المفتاح مباشرة في الكود). ثم أنشأنا كائن client من الفئة OpenAI والمفتاح معطى له. بعد ذلك استخدمنا client.responses.create() لإرسال طلب من نوع “إكمال/استجابة” (حسب Responses API الحديثة) إلى النموذج gpt-4o-mini. وضعنا الاستفسار في الحقل input، ويمكن أيضًا تمرير تعليمات في instructions أو رسائل إضافية إذا لزم الأمر – لكن هنا استخدمنا Prompt بسيط. حددنا max_output_tokens=200 لضمان أن الإجابة لن تتجاوز 200 توكن (حوالي 150 كلمة تقريبًا). وأخيرًا استخرجنا النص الناتج عبر response.output_text وقمنا بعرضه.

عند تشغيل هذا البرنامج (وتوفير مفتاح API صحيح)، سيقوم بالاتصال بخدمة OpenAI وتوليد رد. على سبيل المثال، قد يكون المخرج شيئًا مثل:

لا تشارك مفتاح API علنًا أبدًا. قم بتخزينه في متغيرات بيئية أو في ملفات إعدادات آمنة، وتجنب إدراجه في الشفرة المصدرية. كما يُنصح بتغيير المفتاح بشكل دوري ومراقبة استخدامه عبر لوحة التحكم.

كما ترى، الجواب (المطبوع من النموذج) يعطي نصيحة حول أفضل الممارسات – وهي بالفعل تتوافق مع التوصيات الرسمية التي قدمناها (وقد قمنا بتوثيقها بالمصادر أيضًا). هذا مجرد مثال بسيط، ويمكنك تعديل الـinput لأي سؤال أو مهمة أخرى لترى كيف تكون الإجابات.

ملاحظات حول استخدام مكتبة Python: أحدث إصدار من مكتبة OpenAI Python (إصدار 1.0 فما فوق) يستخدم الواجهة الجديدة OpenAI() كما في المثال. في الإصدارات القديمة، ربما كنت سترى استخدام openai.ChatCompletion.create(...) مباشرة؛ هذا النهج قديم الآن وتم استبداله لضمان التوافق مع التحديثات الجديدة (مثل Responses API). لذا تأكد من تحديث المكتبة للاستخدام الأمثل. أيضًا عند التعامل مع الاستجابات، كائن response يحتوي معلومات أكثر من مجرد النص؛ response.id هو معرف الاستجابة السابقة لاستخدامه مع previous_response_id، وليس معرف المحادثة.
إذا استخدمت Conversations API فمعرف المحادثة يكون conversation.id، وهو شيء مختلف.

مثال عملي: استخدام Responses API مع جافاسكريبت/Node.js

الآن سنقوم بمثال مماثل باستخدام Node.js (مع دعم TypeScript). توفر OpenAI أيضًا حزمة رسمية للـNode باسم openai يمكن تثبيتها من خلال npm:

npm install openai

سنكتب سكربت بسيط (يمكن أن يكون ملف example.mjs) يرسل طلبًا إلى Responses API ويطبع النتيجة في الطرفية.

مثال: سكربت Node.js يستدعي Responses API

import OpenAI from "openai";

// إنشاء عميل OpenAI باستخدام مفتاح API من متغير البيئة
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

// إرسال طلب إلى Responses API
const response = await client.responses.create({
  model: "gpt-5.4",
  input: "Explain the significance of the Turing Test in AI."
});

// طباعة النص الناتج
console.log(response.output_text);

شرح ما يحدث: استخدمنا عبارة import OpenAI from "openai" لاستيراد الكلاس من الحزمة (هذه الصيغة تدعمها Node.js الحديثة، ويمكنك استخدام import أو require حسب تهيئة مشروعك). أنشأنا كائن client ومررنا له مفتاح API من متغير البيئة (والبديل أن تضع المفتاح مباشرة كسلسلة نصية إن كنت تختبر سريعًا لكن لا تفعل ذلك في الإنتاج). بعد ذلك، استخدمنا client.responses.create بنفس الأسلوب كما في بايثون، وحددنا هذه المرة النموذج "gpt-5.4" كمثال على نموذج حديث يمكن استخدامه عبر Responses API. وأعطيناه إدخالًا (بالإنجليزية هنا للتجربة) يطلب شرح اختبار تورينغ وأهميته في الذكاء الاصطناعي. ثم ببساطة نطبع response.output_text إلى وحدة التحكم.

عند تشغيل هذا السكربت (مثلاً بـ node example.mjs)، سيظهر رد من النموذج gpt-5.4 يشرح اختبار تورينغ. مثلاً قد يكون الناتج (مختصرًا):

The Turing Test, proposed by Alan Turing in 1950, is significant because it was one of the first concepts to measure a machine's ability to exhibit intelligent behavior ... (شرح مفصل) ...

هذا يدل على أن التكامل يعمل والنموذج يولد نصًا كما هو متوقع.

ملاحظات حول مكتبة Node.js: مثل مكتبة بايثون، تتعرف مكتبة OpenAI JavaScript تلقائيًا على مفتاح API من متغير البيئة OPENAI_API_KEY إن وُجد، لذا يمكنك غالبًا إنشاء new OpenAI() بدون تمرير مفتاح وسيستخدم ما هو مخزن في البيئة. في المثال أعلاه مررناه صراحةً لمزيد من الوضوح. أيضًا المكتبة تدعم TypeScript بشكل جيد، وستحصل على تعريفات أنواع لـ response وغيره. بالنسبة إلى نماذج المحادثة، response.output_text يوفر النص مباشرة، ولكن لو أردت معلومات أكثر تفصيلاً يمكنك تفحص الكائن response بأكمله.

كذلك، إذا أردت استخدام الرسائل المتعددة أو الوظائف (Function Calling) أو غيرها من الميزات المتقدمة، يمكنك بدلاً من input استخدام بنية محادثة مناسبة أو تعريف الأدوات عبر tools عند الحاجة (في النماذج التي تدعم استدعاء الأدوات)، حسب حاجتك. توثيق المكتبة الرسمية على GitHub يوفر أمثلة إضافية عديدة.

الآن، بعد رؤية الأمثلة العملية، لنلقِ نظرة أقرب على أهم المعلمات التي استخدمناها في طلبات Responses API وما تعنيه.

شرح أهم معلمات طلبات Responses API (model – input – max_output_tokens … إلخ)

عند استدعاء Responses API هناك العديد من المعلمات التي يمكن (وأحيانًا يجب) تحديدها لضبط عمل النموذج. سنركز على 3 معلمات أساسية تم ذكرها في المطلوب: model, input, max_output_tokens، كما سنوضح أيضًا معلمات أخرى مهمة مثل درجة الحرارة وعدد الإجابات وغيرها باختصار لتمام الفائدة.

ومن المعلمات الحديثة التي قد تظهر في بعض النماذج أيضًا:

• reasoning.effort لتحديد مقدار الجهد الاستدلالي الذي يبذله النموذج.
• text.verbosity للتحكم في مستوى التفصيل أو الإسهاب في النص الناتج.
• service_tier لاختيار طبقة التنفيذ المناسبة عند توفر أكثر من مستوى معالجة.
• tools و tool_choice لتعريف الأدوات التي يمكن للنموذج استخدامها أثناء الإجابة.

model (النموذج): هذا المعامل إجباري في كل طلب، وهو يحدد أي نموذج ذكاء اصطناعي تريد استخدامه. إذا لم تكن متأكدًا من نقطة البداية اليوم، فابدأ عادةً بـ gpt-5.4 للمهام العامة المعقدة والبرمجة، أو gpt-5-mini عندما تكون الكلفة والسرعة أهم. ويمكن تقديم GPT-4.1 باعتباره أقوى نموذج non-reasoning حاليًا، بينما يظل GPT-4o وgpt-4o-mini متاحين في الـAPI لكنهما لم يعودا نقطة البداية الافتراضية للمشاريع الجديدة. أما GPT-3.5 Turbo فما يزال متاحًا، لكنه مصنف Legacy ولم يعد الخيار الموصى به للمشاريع الجديدة. وتذكر OpenAI صراحةً أنه منذ يوليو 2024 يُنصح باستخدام gpt-4o-mini بدلًا من GPT-3.5 Turbo لأنه أرخص، وأكثر قدرة، ومتعدد الوسائط، وبنفس السرعة تقريبًا. لذلك إن كانت المهمة بسيطة والتكلفة مهمة، فابدأ عادةً بـ gpt-4o-mini بدلًا من GPT-3.5 Turbo، ثم انتقل إلى نموذج أعلى عند الحاجة.

input (المدخل): هذا المعامل يستخدم في Responses API ليحمل النص الذي تريد من النموذج معالجته أو الإجابة عليه. يمكن أن يكون سؤالًا أو طلبًا أو حتى جزءًا من محادثة. في الصيغة القديمة (Chat Completions API) لم يكن هناك input مباشر بل قائمة messages كما شرحنا سابقًا. حاليًا مع Responses API، إذا كان لديك محادثة متعددة الرسائل، إما: أن تستخدم messages بدل input (والـSDK تدعم ذلك على الأرجح لضمان التوافق مع الأسلوب القديم)، أو تستخدم حقل input فقط وتعتمد على ميزتي instructions وprevious_response_id لإيصال السياق. مثلما رأينا، instructions يمكن أن تحل محل رسالة النظام، وinput تحل محل آخر رسالة من المستخدم، وprevious_response_id يحدد للموديل أنك تكمل على محادثة سابقة محددة.في الاستخدام البسيط (سؤال وجواب منفرد)، يكفي تمرير النص في input. يمكن أن يكون بأي لغة (يدعم النموذج العربية والإنجليزية وغيرهما). إذا أردت أن يكون المساعد ثنائي اللغة أو بأي شخصية خاصة، يمكن تضمين ذلك في instructions. على سبيل المثال:

{
  "model": "gpt-4o",
  "instructions": "أنت مدرس فيزياء خبير تجيب باختصار.",
  "input": "ما هو الثقب الأسود؟"
}

سيأخذ النموذج هذه التعليمات بعين الاعتبار عند توليد الإجابة

max_output_tokens: يحدد هذا المعامل الحد الأقصى لعدد التوكنات التي يمكن للنموذج توليدها في الاستجابة. ويشمل ذلك النص النهائي الظاهر للمستخدم وقد يشمل أيضًا توكنات الاستدلال (reasoning tokens) في بعض النماذج، لذلك قد تكون الإجابة الفعلية أقصر من القيمة المحددة. بشكل تقريبي، تعادل 100 توكن نحو 70–80 كلمة باللغة الإنجليزية.

يساعد ضبط max_output_tokens على التحكم في طول الإجابة وتقليل التكلفة. فمثلًا إذا كنت تريد ملخصًا يقارب 100 كلمة، يمكنك تعيين max_output_tokens=150. في واجهة Responses API يُستخدم هذا الاسم، بينما كان يسمى max_tokens في Chat Completions API الأقدم.

كما يجب الانتباه إلى أن لكل نموذج سعة سياق (context window) تشمل المدخلات والمخرجات معًا. لذلك لا يمكن أن يتجاوز مجموع التوكنات هذه السعة، وإلا سيعيد النظام خطأ. وإذا كنت تحتاج حدًا أدنى لطول الإجابة، فمن الأفضل ذكر ذلك صراحةً في تعليمات الـprompt.

هناك معاملات أخرى مهمة أيضًا يجدر بالمطور معرفتها (على الرغم من أن المطلوب لم يذكرها، سنلمح لها سريعًا):

• temperature (درجة الحرارة): رقم عائم بين 0 و2 يضبط عشوائية وتنوع الإجابات. القيمة الافتراضية 1.0. إذا جعلتها منخفضة مثل 0.2 تصبح الإجابات أكثر تحفظًا وتكرر الأكثر احتمالاً (مناسبة للإجابات الدقيقة). وإن رفعتها إلى 1.5 مثلاً، تصبح الردود أكثر تنوعًا وإبداعًا وأقل predictable. لا ينصح عادة بتجاوز 1.0 كثيرًا إلا لحالات خاصة.
• n (عدد الإجابات): يمكنك طلب أكثر من إكمال/إجابة في طلب واحد عبر تحديد n>1. مثلاً n: 3 يجعل النموذج يولد 3 خيارات للإجابة. يأتي ذلك ضمن مصفوفة choices في الاستجابة. هذه الخاصية مدعومة في Chat Completions API، أما في Responses API فلا يدعم n؛ إن أردت إجابات متعددة يجب إجراء طلبات متعددة.
• stop (تسلسل الإيقاف): يمكنك تمرير سلسلة أو قائمة سلاسل نصية، وعند توليد النموذج إذا واجه أي منها سيتوقف عن توليد المزيد. هذا مفيد لإيقاف النص عند نقطة معينة أو منع استمرار الإجابة بعد جملة معينة.
• tools (استدعاء الأدوات / Function Calling): تتيح النماذج الحديثة في OpenAI إمكانية استخدام ما يسمى الأدوات (Tools) داخل الاستجابة. أحد أشهر هذه الأنواع هو Function Calling، حيث يمكن للمطور تعريف دوال معينة مع مخطط يوضح اسم الدالة والمعاملات المطلوبة. وعندما يفسر النموذج طلب المستخدم، قد يقرر استدعاء إحدى هذه الدوال بدلًا من توليد نص عادي. في هذه الحالة يعيد النموذج استجابة منظمة تحتوي على اسم الدالة والمعاملات المقترحة، ليقوم التطبيق بتنفيذ الدالة فعليًا (مثل إجراء بحث في قاعدة بيانات أو استدعاء API خارجي)، ثم يمكن إرسال نتيجة التنفيذ مرة أخرى إلى النموذج لمتابعة الإجابة. في واجهة Responses API الحديثة يتم تعريف هذه الإمكانيات عادة ضمن معامل tools، حيث يُعد Function Calling أحد أنواع الأدوات الممكنة. وتُستخدم هذه الميزة بشكل شائع لبناء تطبيقات ذكية يمكنها التفاعل مع البيانات والأنظمة الخارجية، لكنها ليست إلزامية في كل استخدام للـAPI.

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

الأسعار والتكلفة في Responses API

إحدى أهم النقاط للمطورين هي فهم تكلفة استخدام Responses API وكيفية احتساب الأسعار. يعتمد تسعير OpenAI API على نموذج الدفع حسب الاستخدام (Pay-as-you-go)، أي أنك تدفع مقابل الاستهلاك الفعلي بدلًا من اشتراك شهري ثابت. وفي نماذج النصوص تُحتسب التكلفة عادةً على input tokens وoutput tokens، وقد تُحتسب أيضًا cached input tokens عندما تكون هذه الميزة مدعومة في النموذج. كما أن بعض النماذج تحتسب reasoning tokens ضمن output tokens حتى لو لم تظهر منفصلة في الاستجابة.

تختلف الأسعار بحسب النموذج وبحسب طبقة المعالجة أيضًا. فهناك عادةً Standard للاستخدام المعتاد، وFlex لبعض النماذج بتكلفة أقل مقابل مرونة أعلى في زمن التنفيذ، وPriority لمعالجة أسرع مقابل تكلفة أعلى. كما توفّر Batch API خصمًا قد يصل إلى 50% على المدخلات والمخرجات للمهام غير العاجلة. لذلك من الأفضل عدم التعامل مع أرقام التسعير داخل المقال على أنها أرقام نهائية ثابتة، بل الإشارة دائمًا إلى أن المرجع النهائي هو صفحة التسعير الرسمية لـ OpenAI API. كما قد تختلف الأسعار أيضًا حسب طبقة المعالجة أو طول السياق في بعض النماذج، لذلك يُنصح دائمًا بمراجعة صفحة التسعير الرسمية للحصول على أحدث القيم.

وفيما يلي أمثلة سعرية تمثيلية حديثة مستندة إلى صفحة التسعير الرسمية، مع التنبيه إلى أن الأسعار قد تتغير بمرور الوقت:

• GPT-5.4: يبلغ سعر المعالجة القياسية نحو $2.50 لكل مليون توكن إدخال، و$0.25 لكل مليون توكن إدخال مخزّن مؤقتًا، و$15.00 لكل مليون توكن إخراج. ويُعد هذا النموذج حاليًا من أقوى نماذج OpenAI للمهام المتقدمة التي تتطلب استدلالًا عميقًا أو معالجة معقدة.
• GPT-5 mini: يبلغ سعره نحو $0.25 لكل مليون توكن إدخال، و$0.025 للإدخال المخزّن مؤقتًا، و$2.00 لكل مليون توكن إخراج. ويُعد خيارًا اقتصاديًا مناسبًا عندما تكون السرعة والتكلفة أهم من أقصى قدر ممكن من القدرة الاستدلالية.
• GPT-5.2: يبلغ سعر المعالجة القياسية نحو $1.75 لكل مليون توكن إدخال، و$0.175 لكل مليون توكن إدخال مخزّن مؤقتًا، و$14.00 لكل مليون توكن إخراج. وما يزال متاحًا عبر الـAPI، لكنه يُعد اليوم نموذجًا من الجيل السابق مقارنة بالنماذج الأحدث في سلسلة GPT-5.
• GPT-4.1: يبلغ سعره القياسي نحو $3.50 لكل مليون توكن إدخال، و$0.875 للإدخال المخزّن مؤقتًا، و$14.00 لكل مليون توكن إخراج.
• GPT-4.1 mini: يبلغ سعره نحو $0.70 لكل مليون توكن إدخال، و$0.175 للإدخال المخزّن مؤقتًا، و$2.80 لكل مليون توكن إخراج، ويُعد خيارًا جيدًا للتطبيقات ذات الحمل الكبير أو الاستخدام واسع النطاق.
• GPT-4o: يبلغ سعره نحو $2.50 لكل مليون توكن إدخال، و$1.25 للإدخال المخزّن مؤقتًا، و$10.00 لكل مليون توكن إخراج. وقد كان أحد النماذج متعددة الوسائط الأساسية في المنصة، وما يزال متاحًا عبر الـAPI.
• gpt-4o-mini: يبلغ سعره نحو $0.15 لكل مليون توكن إدخال، و$0.075 للإدخال المخزّن مؤقتًا، و$0.60 لكل مليون توكن إخراج. ولهذا يُعد خيارًا عمليًا منخفض التكلفة عندما تحتاج نموذجًا سريعًا وفعالًا لتطبيقات المحادثة أو الأتمتة العامة.
• GPT-3.5 Turbo: ما يزال متاحًا عبر الـAPI، لكن OpenAI تصنّفه Legacy، ولم يعد الخيار الموصى به للمشاريع الجديدة. لذلك يُفضَّل تقديمه في المقال باعتباره نموذجًا أقدم ما يزال مدعومًا، وليس نقطة البداية الافتراضية للتطبيقات الحديثة.
• نماذج أخرى: لدى OpenAI أيضًا تسعير مستقل لواجهات أخرى مثل Embeddings والصوت والصور. فعلى سبيل المثال، تبلغ تكلفة text-embedding-3-small نحو $0.02 لكل مليون توكن، وتبلغ تكلفة text-embedding-3-large نحو $0.13 لكل مليون توكن، بينما تبلغ تكلفة Whisper لمعالجة الصوت نحو $0.006 للدقيقة.

باختصار، لا تعتمد تكلفة Responses API على “عدد الطلبات” فقط، بل على نوع النموذج، وعدد التوكنات، وطبقة المعالجة، ووجود caching أو Batch processing. لذلك من الأفضل دائمًا اختيار النموذج المناسب للمهمة، وتقليل التوكنات غير الضرورية في المدخلات، وضبط max_output_tokens بعناية، ومراجعة صفحة التسعير الرسمية ولوحة الاستخدام بشكل دوري.

ملاحظة: لا يُفضَّل افتراض أن كل حساب جديد يحصل على رصيد مجاني ثابت بالقيمة نفسها، لأن نوع الفوترة والعروض المتاحة قد تختلف من حساب لآخر. حاليًا تُسجَّل الحسابات الجديدة في API عادةً ضمن نظام Prepaid Billing، حيث يمكن شراء رصيد يبدأ من $5، وتُستهلك أي free credits متاحة في الحساب أولًا قبل الرصيد المدفوع. لذلك يبقى المرجع الأدق هو صفحة Billing داخل حسابك، لا افتراض رقم مجاني ثابت أو حد إنفاق موحد لكل المستخدمين.

للاطلاع على صفحة التسعير الرسمية المحدثة لـ OpenAI API يمكنك زيارة صفحة الأسعار من هنا.

أفضل ممارسات الأمان عند استخدام Responses API

الأمان هنا يركز على ثلاثة جوانب: حماية مفاتيح API، وحماية البيانات الحساسة وفهم كيفية تعامل OpenAI API معها، والالتزام بسياسات الاستخدام لمنع أي مخاطر قانونية أو تقنية. سنغطي النقاط الأبرز التي يجب على كل مطور اتباعها عند التعامل مع واجهة Responses API:

1. حماية مفتاح API: كما شددنا سابقًا، مفتاح API يجب التعامل معه كسرّ لا يجوز تسريبه. لا تضع المفتاح أبدًا في كود الواجهة الأمامية (Front-end) أو أي بيئة يمكن للمستخدم النهائي الوصول إليها. هذا يعني تجنب وضعه في تطبيق JavaScript يعمل في المتصفح أو تطبيق موبايل غير آمن. دائمًا مرّر الطلبات عبر خادمك الخلفي بحيث يبقى المفتاح مخفيًا في الخادم. أيضًا لا ترفع المفتاح إلى مستودعات عامة (مثل GitHub). هناك روبوتات تفحص المستودعات العامة تلقائيًا بحثًا عن مفاتيح مكشوفة! لذا اتبع ممارسات مثل استخدام ملفات إعدادات محلية أو متغيرات البيئة كما وضحنا. العديد من حالات إساءة الاستخدام حدثت لمطورين تركوا مفاتيحهم مكشوفة عن طريق الخطأ.
2. استخدم مفاتيح متعددة عند الحاجة: توفر OpenAI إمكانية إنشاء عدة مفاتيح API ضمن نفس الحساب (أو المنظمة). من الجيد توليد مفتاح منفصل لكل خدمة أو لكل مطور في فريقك. هكذا لو احتجت إلغاء مفتاح أو حدث سوء استخدام على مفتاح محدد يمكنك إبطاله دون تعطيل بقية خدماتك. كما يمكنك تتبع الاستخدام لكل مفتاح بشكل منفصل.
3. تخصيص الصلاحيات (للمفاتيح المتقدمة): في الإصدارات الجديدة، OpenAI سمحت بإنشاء مفاتيح بمستويات أذونات مختلفة لبعض الخدمات. تأكد من إعطاء كل مفتاح أقل قدر من الصلاحيات التي يحتاجها فقط (مبدأ الأقل امتيازًا) – راجع منصة الإدارة لترى الخيارات المتاحة، فقد تستطيع مثلاً تحديد أن مفتاحًا معينًا لا يستخدم إلا لنماذج معينة أو يندرج تحت مشروع معين.
4. تأمين الخادم والتواصل: تأكد أن الاتصالات من تطبيقك إلى خادمك ومن خادمك إلى OpenAI كلها تتم عبر HTTPS لتشفير البيانات أثناء النقل. والبيانات التي ترسلها قد تكون حساسة، لذلك ينبغي تقليل إرسال المعلومات الشخصية أو السرية إلى الحد الأدنى، أو معالجتها بطريقة آمنة ومجزأة كلما أمكن. ومن المهم هنا تصحيح نقطة شائعة الالتباس: بحسب وثائق OpenAI الحالية، لا تُستخدم البيانات المرسلة إلى OpenAI API لتدريب أو تحسين النماذج افتراضيًا منذ 1 مارس 2023، إلا إذا اختار العميل صراحةً المشاركة في تحسين النماذج (opt-in).
   ومع ذلك، قد تُنشأ سجلات لمراقبة إساءة الاستخدام (abuse monitoring logs) تحتوي على بعض المدخلات أو البيانات الوصفية المشتقة منها، وتُحتفظ عادةً لمدة تصل إلى 30 يومًا قبل حذفها. كما قد تحتفظ بعض الميزات بما يُعرف باسم الحالة التشغيلية (Application State) اللازمة لتنفيذ الطلب أو استمرار الجلسة، ويختلف هذا النوع من التخزين عن استخدام البيانات في تدريب النماذج.
   في بعض الواجهات مثل /v1/responses قد تُحتفظ الحالة التشغيلية لفترة محدودة، بينما قد تحتفظ واجهات مثل Conversations API ببيانات المحادثة حتى يتم حذفها صراحةً. وللعملاء المؤهلين، قد تتوفر خيارات إضافية مثل Modified Abuse Monitoring أو Zero Data Retention وفق سياسات OpenAI. وإذا كانت لديك متطلبات أكثر حساسية، فقد تكون خيارات مثل Modified Abuse Monitoring أو Zero Data Retention متاحة للعملاء المؤهلين بعد موافقة OpenAI.
5. فهم أنواع التخزين في OpenAI API: لا يعني إرسال البيانات إلى OpenAI API وجود نوع واحد فقط من الاحتفاظ بالبيانات. فالوثائق تفرّق بين سجلات مراقبة إساءة الاستخدام، وهي سجلات افتراضية قد تُحتفظ حتى 30 يومًا للمساعدة في إنفاذ سياسات الاستخدام والحد من الاستخدام الضار، وبين الحالة التشغيلية (Application State) التي تُحفظ في بعض الميزات لتلبية الطلب أو استمرار الجلسة. فهم هذا الفرق مهم جدًا عند تصميم التطبيقات الحساسة، لأنه يوضح أن الاحتفاظ التشغيلي أو الأمني لا يعني تلقائيًا استخدام البيانات في تدريب النماذج.
6. مراقبة الاستخدام ووضع تنبيهات: ادخل دوريًا إلى لوحة تحكم الاستخدام في حساب OpenAI لمتابعة استهلاك التوكنات والتكلفة. إذا رأيت ارتفاعًا غير معتاد فقد يكون ذلك مؤشر على تسرب مفتاح أو استخدام غير طبيعي من تطبيقك. يمكنك أيضًا إعداد تنبيهات بريدية أو عبر Slack من خلال خدمات تراقب الاستهلاك (هناك تكاملات ممكنة عبر الـAPI أيضًا لجلب معلومات الاستخدام).
7. التعامل الآمن مع مدخلات المستخدم: صحيح أن نموذج ChatGPT قوي، لكنه قد ينتج مخرجات غير مرغوبة إن تم تغذيته بمدخلات خبيثة أو تحريضية (مثال: أحدهم قد يحاول إجراء ما يسمى prompt injection للحصول على مخرجات مخالفة أو ليتجاوز النظام تعليماتك). لذا فكر في تطبيق فلاتر أساسية على مدخلات المستخدمين في تطبيقك، واستخدم واجهة المراجعة (Moderation API) من OpenAI إذا لزم الأمر. Moderation API متاحة مجانًا وتساعد في التحقق من أن المحتوى غير مخالف قبل إرساله للنموذج.
8. سياسات المحتوى والاستخدام: تأكد من قراءة سياسات OpenAI للاستخدام المفصلة على موقعهم. استخدام الـAPI في تطبيق تجاري يتطلب منك الالتزام بهذه السياسات (مثلاً منع استخدام النموذج لتوليد محتوى كراهية أو تضليل، والتنبيه بأنه قد ينتج أحيانًا معلومات غير صحيحة “هلوسة”). كما يجب أن تذكر لمستخدميك بوضوح أن هناك AI وراء الخدمة وأنها قد تكون لها حدود معرفية (وفق شروط OpenAI).
9. تحديثات المفاتيح بانتظام: من المستحسن تدوير (تغيير) مفاتيح API بشكل دوري كل بضعة أشهر، خاصة إذا كنت تعتقد أن هناك احتمال أنها تعرضت. إلغاء مفتاح قديم وإنشاء آخر جديد ثم تحديثه في خوادمك يضمن أنه حتى لو كان هناك تسريب سابق، المفتاح القديم لم يعد صالحًا.

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

حدود الاستخدام (Rate Limits) والتعامل مع أخطاء API

عند العمل مع Responses API، قد تواجه أحيانًا رسالة خطأ من الخادم تفيد بأنك تجاوزت حدود المعدل المسموح (Rate Limit) أو الحد الأقصى للحصة (Quota). أيضًا قد تظهر أخطاء شائعة أخرى كالأخطاء في طلب غير صحيح أو أخطاء في الخادم. سنناقش هنا أهم تلك الأخطاء وكيفية التعامل معها.

حدود المعدل Rate Limits

ما هي؟ تعتمد OpenAI نظام Rate Limits لتنظيم عدد الطلبات والتوكنات التي يمكن إرسالها خلال فترة زمنية محددة. تُدار هذه الحدود عادةً على مستوى المنظمة أو المشروع داخل حساب المطور، وليس على مستوى المستخدم فقط. وغالبًا ما تظهر بصيغ مثل RPM (الطلبات في الدقيقة) وTPM (التوكنات في الدقيقة)، وأحيانًا RPD أو TPD للاستخدام اليومي، وذلك حسب النموذج المستخدم ومستوى الاستخدام. عادةً تبدأ الحسابات الجديدة بحدود متحفظة نسبيًا، ثم قد ترتفع تدريجيًا مع الاستخدام المنتظم وارتفاع مستوى الثقة في الحساب.

كيف أعرف حدودي؟ يمكنك معرفة حدود حسابك من خلال لوحة التحكم (قسم API Keys أو Usage قد يعرض limits) أو عبر الرسالة التي تصلك في الخطأ. مثلًا إذا تجاوزت الحد سيقول الخطأ شيئًا مثل: “Rate limit reached for gpt-4o-mini: Limit 20 requests/min, please try again later.”. كما تعيد واجهة OpenAI في ترويسات الاستجابة معلومات عن المتبقي من حدودك الحالية: ترويسات مثل x-ratelimit-remaining-requests وx-ratelimit-reset-requests تحدد كم تبقى لك ومتى سيُعاد ضبط العداد.

ماذا أفعل عند الحصول على خطأ 429 (Too Many Requests)? رمز الحالة HTTP 429 يعني أنك إما تجاوزت معدل الطلبات المسموح أو استهلكت كامل حصتك المالية/الشهرية. الرسالة المصاحبة توضح السبب:

• إذا كانت “Rate limit reached for requests” أو “tokens per min” فهذا معدل لحظي.
• إذا كانت “You exceeded your current quota, please check your plan and billing” فهذا يعني انتهى رصيدك أو وصلت الحد الأقصى للإنفاق.

في حالة معدل الطلبات: الحل هو الإنتظار والتخفيف من حدة الطلبات. ينصح بتنفيذ استراتيجية التراجع التدريجي (exponential backoff) لمحاولة إعادة المحاولة تلقائيًا بعد فواصل زمنية متزايدة. على سبيل المثال: عند تلقي 429، انتظر 1 ثانية ثم أعد الطلب، إن تكرر الخطأ انتظر 2 ثانية، ثم 4 ثوان، وهكذا. هذا يمنح الخادم فرصة لمعالجة التراكم وإفساح المجال ضمن نافذة الدقيقة. أيضًا تجنب إرسال دفعات كبيرة فجأة؛ وزّع طلباتك بانسيابية أكثر على مدار الوقت. إذا كنت تتوقع حاجة لتجاوز الحدود (مثلاً تطبيقك ينمو وعدد المستخدمين كبير)، يمكنك التواصل مع دعم OpenAI أو ملء نموذج طلب رفع limits بعد أن يكون لديك سجل استخدام ملتزم ومنتظم.

في حالة تجاوز الحصة المالية: ستظل تواجه 429 بمعنى نفاد الرصيد إلى أن ترفع الحد بالاتصال بالدعم أو حلول الدورة القادمة (الشهر الجديد). لذلك تأكد من مراقبة فاتورتك أيضًا وليس فقط المعدلات اللحظية.

أخطاء أخرى شائعة

• رمز 401 Unauthorized: يعني فشل في المصادقة. غالبًا مفتاح API غير صحيح أو مفقود. تأكد أنك ترسله في الترويسة بالشكل الصحيح. أحيانًا يحدث إذا كان المفتاح صحيح لكن الحساب نفسه ليس لديه صلاحية (مثلاً نسيت الانضمام لمؤسسة تمت دعوتك إليها). الحل هو مراجعة مفتاحك وإعدادات حسابك. ربما جرّب إنشاء مفتاح جديد إذا استمرت المشكلة.
• رمز 400 Bad Request: هذا يعني أن هناك خطأ ما في صيغة الطلب الذي أرسلته. ربما حقل مفقود أو قيمة غير صالحة. رسالة الخطأ التي تأتي في الرد غالبًا تعطي تفاصيل. مثال: إذا أرسلت اسم نموذج خطأ أو نسيت حقل “model”، سترى رسالة خطأ تفسيرية من نوع invalid_request_error. الحل هنا هو مراجعة صيغة الـJSON المرسل ومطابقته مع التوثيق.
• رمز 403 Forbidden: هذا قد يحدث مثلاً إذا حاولت الوصول إلى مورد ليس مصرح لك به (كأن تستخدم نموذج لم يتم إتاحة الوصول إليه لحسابك). وأحيانًا يظهر إذا كنت تحاول استخدام الـAPI من بلد محظور جغرافيًا.
• رمز 500 أو 502/503 Server Errors: هذه أخطاء من طرف خادم OpenAI. 500 عام يعني خطأ غير متوقع في المعالجة. 502 Bad Gateway أو 503 Service Unavailable تعني أن الخادم مثقل أو هناك عطل مؤقت. في هذه الحالات الحل هو الانتظار وإعادة المحاولة بعد قليل. تأكد أيضًا من حالة منصة OpenAI عبر status.openai.com إن كنت ترى أخطاء خادم كثيرة، فقد يكون هناك انقطاع معلن.
• خطأ “Slow down”: أحيانًا يعيد الخادم 503 مع رسالة “Slow down, you sent too many requests too fast.” هذا شبيه بمشكلة الـRate Limit لكن تحديدًا يعني أنك زدت الارسال بسرعة مفاجئة. الحل كما تقترح الرسالة: قلل معدل الإرسال وانتظر على الأقل 15 دقيقة قبل محاولة زيادة المعدل مرة أخرى بشكل تدريجي.
• أخطاء المحتوى (التصفية): إذا تضمن رد النموذج محتوى غير ملائم أو محظور، قد يقوم النظام بإرجاع خطأ أو رسالة تشير إلى انتهاك سياسة المحتوى (Content Filter). في Responses API، قد يظهر finish_reason باسم “content_filter” مثلاً. الحل هنا هو مراجعة الـprompt والتأكد أنه لا يطلب أمور مخالفة، أو توفير توجيهات أو معلومات للمستخدم بشكل أن المحتوى لا يخرق السياسة.

استراتيجيات التعامل مع الأخطاء:

1. برمج تطبيقك بحيث يعالج الاستجابات الخطأ بشكل أنيق: مثلاً إن حصل 429، أظهر للمستخدم رسالة “الخادم مشغول حاليًا، نحاول إعادة المحاولة…” بدل أن يعلق التطبيق بصمت. وقم فعليًا بإعادة المحاولة تلقائيًا باستخدام backoff كما ذكرنا.
2. في حالة الأخطاء غير القابلة للحل مباشرة، قدّم للمستخدم اعتذارًا أو بدائل. مثلاً إذا انقطع الاتصال أو خادم OpenAI معطل، يمكنك إبلاغ المستخدم أن الخدمة غير متاحة مؤقتًا.
3. راقب أكواد الخطأ واحصائياتها: ربما تجد أن تطبيقك يقترب من حدود المعدل كثيرًا فتفكر في حلول مثل التخزين المؤقت (caching) لبعض الإجابات أو تجميع الطلبات (batching) إذا أمكن لتقليل عدد الاستدعاءات المنفصلة.

أخيرًا، من المفيد خلال التطوير والاختبار استخدام بيئات مختلفة (Development vs Production) وربما مفاتيح منفصلة، بحيث لو حصل خطأ مدمر أو استهلاك هائل في بيئة التطوير لا يؤثر على حد الإنتاج. OpenAI تتيح إنشاء مؤسسات (Organizations) لتقسيم الاستخدام وهو خيار إن كان فريقك كبيرًا أو تدير حسابات متعددة.

الأسئلة الشائعة (FAQ)

خاتمة

قدمنا في هذه المقالة دليلًا تقنيًا شاملًا للتعامل مع واجهة برمجة تطبيقات ChatGPT (OpenAI API) موجه خصيصًا للمطورين. تعرفنا على تعريف Responses API وكيف أنه يفتح الباب لدمج قدرات نماذج الذكاء الاصطناعي اللغوية في مختلف التطبيقات بشكل سلس. استعرضنا الفروق الجوهرية بين استخدام ChatGPT من خلال الواجهة العادية واستخدامه برمجيًا عبر API من حيث المرونة والتحكم والسياق والكلفة.

غطينا أيضًا آلية عمل Responses API خطوة بخطوة، لفهم ما يحدث تحت الغطاء عند إرسال طلب والحصول على استجابة. ثم شرحنا كيفية الحصول على مفتاح API وضبطه، وأكدنا على أهم النصائح للمحافظة على سريته. انتقلنا إلى أمثلة عملية باللغتين Python وNode.js لاستخدام API عمليًا، مع توضيح كيفية كتابة كود صحيح ومتوافق مع أحدث إصدار من الـSDK، مع أمثلة حية لكيفية طباعة النتائج.

في قسم معلمات الطلبات، وضحنا أدوار المعاملات المهمة كاختيار النموذج المناسب (model)، وتضمين المدخلات (سواء عبر input أو messages)، وتقييد طول المخرجات عبر max_output_tokens، بالإضافة إلى الإشارة للمعاملات الأخرى كالحرارة والتوقف وعدد النتائج واستدعاء الدوال. هذه المعرفة التفصيلية تساعد في ضبط سلوك النموذج للحصول على النتائج المرجوة بكفاءة.

كما فصلنا هيكلية التسعير وكيف تُحسب تكلفة استخدام Responses API، مع عرض أمثلة سعرية حديثة للنماذج الشائعة مثل gpt-5-mini وgpt-5.4 وGPT-4.1، مع التنبيه إلى أن المرجع النهائي للأسعار هو صفحة التسعير الرسمية لـ OpenAI API لأنها قابلة للتحديث. شددنا على كون الخدمة باستهلاك مدفوع لكل توكن، ونصحنا باتباع أساليب لخفض الاستخدام غير الضروري وتقليل التكلفة، مع مراقبة لوحة الاستخدام تجنبًا للمفاجآت.

من الناحية العملية والأمنية، ناقشنا أفضل الممارسات الأمنية التي يجب أن يلتزم بها المطورون: حماية مفاتيح API من التسرب، وعدم تضمينها في التطبيقات الأمامية، ومتابعة الصلاحيات والاستخدام، والتأكد من الامتثال لسياسات OpenAI. هذه الممارسات تبني الثقة والموثوقية في التطبيق وتعزز تجربة المستخدم الآمنة.

أخيرًا تناولنا التعامل مع الحدود والأخطاء: من فهم نظام معدلات التحديد (Rate Limits) وكيفية تجنب تجاوزها أو معالجته عبر التراجع التدريجي، إلى مناقشة رموز الأخطاء الشائعة (401, 429, 500, 503 وغيرها) وما تعنيه الحلول المقترحة لكل منها. إن التعامل الصحيح مع أخطاء API بشكل استباقي هو جزء أساسي من بناء تطبيق احترافي، لضمان استمرارية الخدمة وعدم توقفها عند أول مشكلة.

باختصار، ChatGPT واجهة جاهزة للمستخدم النهائي، بينما Responses API واجهة تطوير مخصصة لبناء منتجاتك فوق نماذج OpenAI. قد تتشابه بعض القدرات بين الطرفين، لكن لا يصح التعامل معهما على أنهما منتج واحد أو على أن النماذج، والتسعير، وحدود الاستخدام فيهما متطابقة دائمًا.