يبحث مطورون كثيرون عن «ChatGPT API»، لكن الاسم الأدق للخدمة البرمجية هو OpenAI API. تتيح لك الواجهة إرسال نصوص وصور وملفات إلى نماذج OpenAI من خادمك، ثم استخدام الناتج داخل موقع أو تطبيق أو سير عمل. أما ChatGPT فهو منتج جاهز للمستخدم، وليس الاسم التقني لواجهة المطورين.
يركز هذا الدليل على Responses API: إنشاء مفتاح آمن، وإرسال أول طلب من Python أو Node.js، واختيار نموذج، ومتابعة السياق، ثم التعامل مع المخرجات المنظمة والأدوات والتكلفة والأخطاء والخصوصية. إذا كنت لم تحسم بعد هل تحتاج منتج ChatGPT أم واجهة برمجية، فابدأ بدليل الفرق بين ChatGPT وOpenAI API.
حدود هذا الدليل: أمثلة الكود أدناه مبنية على الصيغة المنشورة في وثائق OpenAI الرسمية وقت التحقق، لكنها لم تُشغّل من حساب GPT Gate أثناء إعداد هذه النسخة؛ لذلك لا نعرض ناتجًا مزعومًا. قد يتوقف التنفيذ على صلاحية حسابك، وتوفر النموذج، وإعداد الفوترة، ونسخة المكتبة الحالية.
ما الذي تحتاجه قبل البدء؟
تحتاج إلى حساب على منصة OpenAI، ومشروع تملك صلاحية استخدامه، ومفتاح API، وبيئة خادم تستطيع حفظ الأسرار فيها. تحتاج أيضًا إلى Python أو Node.js إذا أردت استخدام أحد المثالين في هذه الصفحة. إدارة API وفوترتها تتم من منصة المطورين، وهي منفصلة عن اشتراك ChatGPT؛ وجود اشتراك في ChatGPT لا يعني وجود رصيد أو حدود استخدام للـAPI.
ثبّت مكتبة OpenAI الرسمية المناسبة لبيئتك:
pip install openai
أو:
npm install openai
لا تثبت رقم إصدار منسوخًا من مقال قديم. راجع البدء السريع الرسمي إذا تغيّر أمر التثبيت أو احتجت إعدادًا خاصًا بإطار العمل الذي تستخدمه.
إنشاء مفتاح OpenAI API وحمايته
أنشئ المفتاح من صفحة مفاتيح API الرسمية، ثم احفظه في متغير بيئة باسم OPENAI_API_KEY. تستطيع مكتبتا Python وJavaScript الرسميتان قراءته من البيئة دون كتابته داخل الكود.
المفتاح سر يمنح من يحمله قدرة على استخدام مشروعك وتحميل التكلفة عليه. لذلك:
- لا تضعه في كود الواجهة الأمامية أو JavaScript الذي يصل إلى المتصفح.
- لا ترسله في محادثة أو بريد أو لقطة شاشة، ولا تحفظه في مستودع عام.
- استخدم مخزن أسرار في الاستضافة الإنتاجية، وافصل مفاتيح التطوير عن الإنتاج.
- امنح كل مشروع أقل صلاحيات لازمة، وراقب الاستخدام، ودوّر المفتاح فور الشك في انكشافه.
إذا كان تطبيقك يعمل في المتصفح أو الهاتف، فأرسل الطلب إلى خادمك أولًا، وليتصل الخادم بـOpenAI. بهذه البنية لا يصل المفتاح إلى المستخدم النهائي. للمزيد راجع ممارسات الإنتاج الرسمية.
أول طلب عبر Responses API باستخدام Python
بعد ضبط OPENAI_API_KEY، أنشئ عميلًا ثم استدعِ responses.create. يفصل المثال بين instructions، وهي توجيه ثابت لسلوك المساعد، وinput، وهو طلب المستخدم الحالي:
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6",
instructions="أجب بالعربية الفصحى وباختصار.",
input="اشرح مفهوم واجهة API في ثلاث نقاط."
)
print(response.output_text)
يحتوي response.output_text على النص المجمّع الذي ولّده النموذج. لا تخلطه مع بنية choices الخاصة بأمثلة Chat Completions القديمة. توصي وثائق OpenAI الحالية باستخدام Responses API للمشروعات الجديدة التي تحتاج الاستدلال أو الأدوات أو المحادثات متعددة الأدوار.
أول طلب باستخدام Node.js
يؤدي المثال التالي المهمة نفسها في JavaScript على الخادم:
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.create({
model: "gpt-5.6",
instructions: "أجب بالعربية الفصحى وباختصار.",
input: "اشرح مفهوم واجهة API في ثلاث نقاط."
});
console.log(response.output_text);
استخدم معالجة أخطاء مناسبة حول الطلب في التطبيق الحقيقي، ولا تطبع المدخلات الحساسة أو المفتاح في السجلات. كما يجب ألا تفترض أن كل استجابة صحيحة واقعيًا؛ طبّق التحقق البشري أو البرمجي المناسب لحساسية الاستخدام. يشرح دليل هلوسة ChatGPT والنماذج اللغوية سبب ضرورة مراجعة الحقائق.
كيف تختار نموذجًا؟
وقت التحقق من هذه الصفحة، يعرض كتالوج OpenAI عائلة GPT-5.6 بثلاثة أدوار عامة:
gpt-5.6-solللمهام المعقدة التي تعطي الأولوية للقدرة، ويشير الاسم المختصرgpt-5.6إليه.gpt-5.6-terraلتحقيق توازن بين القدرة والتكلفة.gpt-5.6-lunaللأحجام المرتفعة والمهام الأكثر حساسية للتكلفة.
هذه نقطة بداية وليست حكمًا بأن نموذجًا واحدًا هو الأفضل لكل تطبيق. جهّز مجموعة طلبات تمثل عملك الحقيقي، ثم قارن دقة النتائج، والالتزام بالشكل، والسرعة، وعدد الرموز، والتكلفة. قد يتغير الكتالوج؛ افحص صفحة النماذج الرسمية قبل النشر، وراجع دليل نماذج شات جي بي تي وOpenAI وسجل تحديثات النماذج للسياق العربي.
متابعة سياق المحادثة
كل طلب مستقل ما لم ترسل إليه السياق المطلوب. مع Responses API تستطيع ربط دور جديد باستجابة سابقة باستخدام previous_response_id:
first = client.responses.create(
model="gpt-5.6",
input="اقترح اسمًا عربيًا لتطبيق ملاحظات."
)
second = client.responses.create(
model="gpt-5.6",
previous_response_id=first.id,
input="اجعل الاقتراح أقصر."
)
print(second.output_text)
توجد أيضًا Conversations API عندما تحتاج كائن محادثة دائمًا عبر جلسات أو أجهزة متعددة. كل رموز الإدخال السابقة في السلسلة تُحاسب كإدخال؛ لذلك لا تعد previous_response_id ذاكرة مجانية. اختر آلية الحالة بعد فهم أثرها في التخزين والخصوصية. اقرأ شرح نافذة السياق ووثيقة إدارة حالة المحادثة.
المخرجات المنظمة وStructured Outputs
النص الحر مناسب للعرض البشري، لكنه غير مثالي عندما ينتظر تطبيقك حقولًا محددة. تتيح Structured Outputs إلزام الناتج بمخطط JSON مدعوم. في Responses API يُحدد الشكل داخل text.format بنوع json_schema مع strict: true ومخطط واضح.
استخدمها عندما تحتاج اسمًا وتصنيفًا ودرجة ثقة بصيغة ثابتة. مطابقة المخطط لا تثبت صحة الحقائق؛ تحقق من البيانات وتعامل مع الرفض أو الإخراج غير المكتمل. لا تدعم الخدمة كل خصائص JSON Schema؛ ومن المتطلبات الحالية جعل الحقول مطلوبة وضبط additionalProperties: false للكائنات. لذلك انسخ البنية من دليل Structured Outputs الرسمي بدل مثال قديم.
الأدوات وFunction Calling بإيجاز
تسمح الأدوات للنموذج بطلب وظيفة يوفّرها تطبيقك، مثل البحث عن طلب شراء أو قراءة قاعدة بيانات. تعرّف الوظيفة باسم ووصف ومعاملات ضمن JSON Schema؛ وقد يعيد النموذج عنصر function_call يتضمن اسم الوظيفة والحجج. عندها يتحقق تطبيقك من الحجج والصلاحيات، وينفذ الوظيفة، ثم يعيد نتيجتها إلى النموذج لاستكمال الإجابة.
النموذج لا يمنح نفسه صلاحية تنفيذ وظائف خادمك. ضع قائمة سماح، وحقق هوية المستخدم، واطلب تأكيدًا قبل أي إجراء مالي أو حذف أو إرسال خارجي. وتوجد أدوات مدمجة من OpenAI، لكن لكل أداة قدرات وتكلفة وسياسة بيانات يجب مراجعتها. التفاصيل في دليل Function Calling.
التكلفة وحدود الاستخدام
لا توجد كلفة واحدة ثابتة لعبارة «ChatGPT API». تتحدد الفاتورة وفق النموذج، ورموز الإدخال والإخراج، والأدوات أو أنماط المعالجة المستخدمة. لذلك لا تعتمد على جدول أسعار منسوخ؛ راجع التسعير الرسمي الحي، وراقب صفحة الاستخدام، واضبط حدود الإنفاق والتنبيهات داخل المشروع.
لخفض التكلفة، أرسل السياق الضروري فقط، وحدد طول الإجابة، واختر النموذج بناءً على قياس حقيقي، وخزّن النتائج التي يجوز إعادة استخدامها. لا تخفّض الجودة عشوائيًا في مهمة حساسة؛ ابنِ تقييمات ثابتة قبل تغيير النموذج أو البرومبت.
تختلف حدود المعدل حسب النموذج والمشروع ومستوى الاستخدام. لا تفترض رقمًا موحدًا. اعرض الحدود الفعلية في حسابك وراجع دليل Rate Limits.
أشهر الأخطاء وكيف تتعامل معها
- 400: الطلب غير صالح؛ راجع أسماء الحقول وأنواعها والمخطط المدعوم.
- 401: مشكلة مصادقة؛ تحقق من المفتاح والمشروع، ولا تطبع المفتاح أثناء التشخيص.
- 403: قد تكون الصلاحية أو المنطقة أو سياسة المشروع سببًا للرفض.
- 429: قد يعني سرعة طلبات مرتفعة، أو حد إنفاق أو استخدام، أو رصيدًا غير متاح. اقرأ رمز الخطأ التفصيلي قبل إعادة المحاولة.
- 5xx: عطل مؤقت من جهة الخدمة؛ سجّل معرّف الطلب وأعد المحاولة ضمن حدود معقولة.
عند خطأ معدل قابل لإعادة المحاولة، احترم ترويسة Retry-After إن وجدت، وإلا استخدم تراجعًا أسيًا مع قدر عشوائي وحد أقصى للمحاولات والوقت. لا تكرر أخطاء المصادقة أو الفوترة بلا توقف؛ الطلبات الفاشلة قد تستهلك جزءًا من الحد. راجع مرجع أخطاء API.
الخصوصية والاحتفاظ بالبيانات
وفق سياسة منصة OpenAI، لا تُستخدم بيانات API لتدريب النماذج افتراضيًا ما لم تختَر مشاركتها. لكن ذلك لا يعني عدم التخزين. قد تُحتفظ سجلات مراقبة إساءة الاستخدام حتى 30 يومًا، وتُحفظ كائنات Responses افتراضيًا 30 يومًا ويمكن ضبط store: false في الحالات المدعومة. لا يساوي هذا الإعداد Zero Data Retention ولا يلغي سجلات مراقبة الإساءة. أما Conversations وعناصرها فقد تستمر حتى حذفها.
تختلف التفاصيل حسب نقطة النهاية، والأداة، وإعدادات المؤسسة، وأهلية Zero Data Retention. كما تخضع البيانات المرسلة إلى خدمة خارجية عبر أداة أو MCP لسياسة تلك الجهة. قبل معالجة بيانات شخصية أو سرية، راجع ضوابط بيانات منصة OpenAI، وطبّق سياسة تقليل البيانات والحذف والموافقة الملائمة للقانون وحالة الاستخدام.
قائمة أمان قبل الإطلاق
- اجعل الاتصال بـOpenAI من الخادم واحمِ المفتاح في مخزن أسرار.
- افصل التطوير عن الإنتاج، واضبط الصلاحيات وحدود الإنفاق والمراقبة.
- تحقق من مدخلات المستخدم ومخرجات النموذج وحجج استدعاء الأدوات.
- لا تسمح للنموذج بتنفيذ إجراء حساس من دون قواعد تفويض وتأكيد.
- قلل البيانات المرسلة، وحدد مدة الاحتفاظ، واحذف ما لم تعد تحتاجه.
- اختبر الجودة والأمان على حالات عادية وحدّية وعدائية تمثل تطبيقك فعلًا.
لأفكار تطبيقية قبل بناء التكامل، راجع استخدامات شات جي بي تي العملية. وإذا كان هدفك مجرد محادثة جاهزة من دون تطوير، يمكنك تجربة شات جي بي تي مجانا بدل إنشاء تكامل API.
أسئلة شائعة عن ChatGPT API
هل ChatGPT API مجانية؟
لا ينبغي اعتبار OpenAI API نسخة مجانية دائمة من ChatGPT. الاستخدام والفوترة والحدود تظهر في حساب منصة المطورين وقد تتغير. افحص إعدادات حسابك وصفحة التسعير الرسمية قبل إرسال طلبات إنتاجية.
هل اشتراك ChatGPT Plus أو أي خطة ChatGPT يشمل رصيد API؟
تُدار اشتراكات ChatGPT وفوترة API بصورة منفصلة. وجود اشتراك في ChatGPT لا يعني تلقائيًا وجود رصيد API.
ما الفرق بين ChatGPT وOpenAI API؟
ChatGPT منتج جاهز للمحادثة، بينما API واجهة لبناء منتجك أو أتمتتك. توجد مقارنة تفصيلية في دليل ChatGPT أم OpenAI API؟.
ما النموذج الذي أبدأ به؟
ابدأ من توصية كتالوج OpenAI الحالية، ثم اختبر على مهام ممثلة لتطبيقك. وقت التحقق كان gpt-5.6 اسمًا مختصرًا للنموذج Sol، مع Terra للتوازن وLuna للأحجام الحساسة للتكلفة. لا تثبت هذا الاختيار للأبد؛ راجع الكتالوج عند كل تحديث مهم.
هل تدعم OpenAI API اللغة العربية؟
ينص كتالوج النماذج الحالية على دعم متعدد اللغات. تختلف جودة العربية حسب المهمة والنموذج والبرومبت، لذا قيّمها باستخدام نصوص عربية حقيقية من جمهورك، ولا تفترض مستوى واحدًا لكل اللهجات أو المجالات.
لماذا يظهر خطأ 429؟
قد يكون السبب معدل طلبات مرتفعًا، أو بلوغ حد إنفاق أو استخدام، أو مشكلة في الرصيد. اقرأ نوع الخطأ التفصيلي؛ أعد المحاولة بتراجع فقط عندما يكون السبب حد معدل مؤقتًا، وعالج الفوترة أو الحد من لوحة الحساب عندما يكون الخطأ متعلقًا بهما.
هل تستخدم OpenAI بيانات API في التدريب؟
ليس افتراضيًا وفق السياسة الرسمية، إلا إذا اشتركت صراحة في مشاركة البيانات. تبقى سياسات الاحتفاظ ومراقبة إساءة الاستخدام منفصلة، لذلك راجع إعدادات نقطة النهاية والمؤسسة قبل إرسال بيانات حساسة.