كيفية استخدام واجهة برمجة تطبيقات OpenAI للاستجابات

يرشدك هذا الدليل خلال استخدام واجهة برمجة تطبيقات استجابات OpenAI من البداية إلى النهاية: بحلول الوقت الذي تنتهي فيه، ستتمكن من إرسال طلب إلى POST /v1/responses، وقراءة المخرجات المتداخلة التي تعيدها، وتشغيل الأدوات المدمجة، والحفاظ على حالة المحادثة عبر المكالمات، والتحقق من العقد بأكمله داخل Apidog. تعد واجهة برمجة تطبيقات الاستجابات هي الواجهة الأحدث من OpenAI لإنشاء مخرجات النموذج، ويشرح الدليل الرسمي للاستجابات سبب توجيه OpenAI الآن للمشاريع الجديدة نحوها. إذا كنت تختبر بالفعل نقطة النهاية الأقدم، فيمكنك إعادة استخدام معظم هذا الإعداد، تمامًا مثل سير العمل في دليل اختبار واجهة برمجة تطبيقات ChatGPT باستخدام Apidog الخاص بنا.

زر

ما تحتاجه أولاً

قبل إرسال طلب، تأكد من توفر بعض الأشياء:

مفتاح OpenAI API مع إمكانية الوصول إلى نموذج عام حالي. احتفظ بالمفتاح في متغير بيئة، ولا تلصقه في أمر أو ملف مشترك.
اسم نموذج يمكن لحسابك استدعاؤه بالفعل. بدلاً من ترميزه بشكل ثابت، تحقق من قائمة النماذج في لوحة تحكم OpenAI الخاصة بك وتأكد منها مقابل نقطة النهاية.
طريقة لإرسال طلبات HTTP الخام وفحص JSON الذي يعود. تعمل المحطة الطرفية المزودة بـ curl للاتصال الأول، وApidog هو ما ستستخدمه لتأكيد الاستجابة ومحاكاتها لاحقًا.

يساعد أيضًا معرفة ما تفعله نقطة النهاية قبل استدعائها. تكشف واجهة برمجة تطبيقات الاستجابات عن نقطة نهاية واحدة، POST /v1/responses. ترسل اسم نموذج وinput، وتحصل على كائن استجابة يمكن أن يحتوي على نص عادي، واستدعاءات دالة، ونتائج أدوات تستضيفها OpenAI مثل البحث على الويب أو البحث عن الملفات. يمكن لعملية استدعاء واحدة تشغيل دور كامل متعدد الخطوات: يقرر النموذج البحث في الويب، ويقرأ النتائج، ثم يكتب إجابة، وتسجل الاستجابة كل خطوة اتخذتها.

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

اعرف كيف تختلف عن Chat Completions

إذا كنت قد استخدمت POST /v1/chat/completions، فإن التغيير يكون في الغالب في الشكل والحالة. يأخذ Chat Completions مصفوفة messages ويعيد choices. أنت تدير النص الكامل بنفسك، وتعيد إرسال كل دور سابق في كل مكالمة. الأدوات هي شيء تقوم بتطبيقه من جانبك.

تأخذ واجهة برمجة تطبيقات الاستجابات input (سلسلة أو قائمة من العناصر المكتوبة) وتعيد output (قائمة من العناصر المكتوبة). يمكنها تخزين الدور لك وتشغيل الأدوات المستضافة دون إضافة تعقيدات.

إليك المقارنة العملية:

الجانب	Chat Completions	Responses API
نقطة النهاية	`POST /v1/chat/completions`	`POST /v1/responses`
جسم الطلب	مصفوفة `messages`	`input` (سلسلة أو عناصر) + `instructions`
شكل المخرجات	`choices[].message`	قائمة `output` من العناصر المكتوبة
حالة المحادثة	تعيد إرسال السجل الكامل	`store` + `previous_response_id`
الأدوات المدمجة	تقوم ببنائها	`web_search`، `file_search`، `code_interpreter`، والمزيد
الحالة	مدعومة، لم يتم الإعلان عن إيقافها	موصى بها للمشاريع الجديدة

لن تختفي Chat Completions. تقول OpenAI إنها ستظل مدعومة، ويمكنك ترحيل سير عمل مستخدم واحد في كل مرة بدلاً من إعادة كتابة كل شيء دفعة واحدة. أما Assistants API فهو تحت العد التنازلي: فقد أعلنت OpenAI عن إيقافه في 26 أغسطس 2025، مع تاريخ توقف محدد في 26 أغسطس 2026، لذلك يجب أن تبدأ أعمال الوكيل الجديدة على Responses.

قم بإجراء طلبك الأول

إليك مكالمة بسيطة. استبدل اسم النموذج بما يمكن لحسابك الوصول إليه، واحتفظ بمفتاحك خارج الأمر نفسه.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'

تمرر ثلاثة أشياء مهمة هنا: model، وinput (الموجه الخاص بك)، وinstructions (التوجيه على مستوى النظام). يؤدي تعيين store إلى true إلى إخبار OpenAI بحفظ الاستجابة حتى تتمكن من متابعة السلسلة لاحقًا.

اقرأ الاستجابة

تبدو الاستجابة المختصرة كما يلي:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}

لاحظ البنية، لأنها الجزء الذي يربك الناس. النص الذي تريده موجود في output[0].content[0].text، وليس في حقل على المستوى الأعلى. تضيف حزم SDK الرسمية أداة وصول مريحة output_text تجمع جميع عناصر النص في سلسلة واحدة، ولكن هذه الخاصية هي أداة مساعدة لـ SDK، وليست جزءًا من JSON HTTP الخام. عندما تستدعي نقطة النهاية مباشرة، تقرأ المسار المتداخل. id على المستوى الأعلى هو ما ستعيد استخدامه للحالة، ويخبرك usage.total_tokens بتكلفة الاستدعاء.

أضف الأدوات المدمجة

الميزة الرئيسية هي أن OpenAI تدير أدوات معينة لك. تقوم بإدراجها في مصفوفة tools ويقرر النموذج متى يستدعيها. تتضمن الأنواع المدمجة المعتمدة:

web_search لعمليات البحث المباشرة على الإنترنت مع الاستشهادات (لا يزال web_search_preview القديم يعمل للتكاملات القديمة ولكنه يفتقر إلى عناصر التحكم الأحدث).
file_search للاسترجاع عبر الملفات التي قمت بتحميلها.
code_interpreter لتشغيل وتحليل التعليمات البرمجية في بيئة اختبار.
computer_use لتشغيل واجهة كمبيوتر.
image_generation لإنتاج الصور مباشرة.

تشغيل إحداها هو إضافة صغيرة إلى الجسم:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

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

تابع المحادثة عبر المكالمات

تعمل الحالة من خلال معلمتين. store يكون افتراضيًا صحيحًا، مما يعني أن OpenAI يحفظ كائن الاستجابة (يتم الاحتفاظ به لمدة 30 يومًا افتراضيًا) ويعيد id. مرر هذا id كـ previous_response_id في مكالمتك التالية ويستمر النموذج في السلسلة دون إعادة إرسال النص:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

إذا كنت تفضل الاحتفاظ بالأشياء بدون حالة، أو كان لديك متطلب عدم الاحتفاظ بالبيانات، فعيّن store على false وادير السياق بنفسك. لتدفقات الصوت والفيديو في الوقت الفعلي ومنخفضة التأخير، تستخدم OpenAI سطحًا مختلفًا؛ يغطي دليل واجهة برمجة تطبيقات GPT في الوقت الفعلي تلك الحالة. وإذا كنت تنسق وكلاء متعدد الخطوات فوق كل هذا، فإن الأنماط تتوافق مع حزمة تطوير وكلاء OpenAI.

كيفية اختباره في Apidog

Apidog عبارة عن منصة لاختبار واجهات برمجة التطبيقات وتصميمها ومحاكاتها. إنها ليست حزمة تطوير برامج OpenAI أو مكتبة تعليمات برمجية، لذلك لن تكتب بايثون مقابلها. بدلاً من ذلك، ما تفعله هو: بناء طلب HTTP الخام إلى /v1/responses، وإرساله، وكتابة تأكيدات على JSON الذي يعود. هذا بالضبط هو نوع فحص العقد الذي يكتشف التكامل المعطل قبل أن يكتشفه المستخدمون.

إليك الإعداد، خطوة بخطوة.

تخزين المفتاح في متغير بيئة

في Apidog، أنشئ بيئة (على سبيل المثال، "OpenAI Prod") وأضف متغيرًا مثل OPENAI_API_KEY. احتفظ بالقيمة في البيئة، وليس في الطلب، حتى لا يتم الالتزام بالسر في مجموعة مشتركة أبدًا. ثم أنشئ طلب POST جديدًا إلى https://api.openai.com/v1/responses وأضف الرأس Authorization: Bearer {{OPENAI_API_KEY}}. يستبدل Apidog المتغير وقت الإرسال.

عيّن الجسم إلى JSON والصق الطلب من قبل. اضغط على إرسال. سترى كائن الاستجابة الكامل، منسقًا، مع مصفوفة output المتداخلة.

التأكد من حقول الاستجابة

الاستجابة الناجحة 200 ليست دليلاً على أن الاستجابة مصممة بالشكل الذي يتوقعه تطبيقك. أضف تأكيدات حتى يفشل الانحدار بصوت عالٍ. عمليات التحقق المفيدة مقابل رد /v1/responses:

status يساوي completed.
output[0].content[0].text موجود وغير فارغ.
usage.total_tokens أكبر من 0.
عندما ترسل tools، يحتوي عنصر في output على type يساوي web_search_call.

يتيح لك منشئ التأكيدات المرئية في Apidog استهداف مسارات JSON هذه دون كتابة نصوص اختبار، ويوضح قالب حالة اختبار API الخاص بنا كيفية هيكلة هذه الفحوصات. احفظ الطلب في مجموعة ويصبح اختبارًا قابلاً للتكرار يمكنك تشغيله في CI.

محاكاة الاستجابة للتطوير دون اتصال بالإنترنت

تتطلب مكالمات OpenAI المال وتتطلب الوصول إلى الشبكة، وهو أمر محرج عندما تقوم ببناء واجهة المستخدم التي تستهلك الاستجابة أو تشغيل الاختبارات في مسار لا ينبغي أن يضرب واجهة برمجة تطبيقات مدفوعة. تحل ميزة المحاكاة في Apidog هذه المشكلة. احفظ حمولة /v1/responses تمثيلية كمحاكاة، ووجه تطبيقك إلى عنوان URL للمحاكاة في Apidog، وستحصل واجهة المستخدم الأمامية على شكل JSON الصحيح مع عدم إنفاق أي رمز مميز. عندما تتغير نقطة النهاية الحقيقية، تقوم بتحديث محاكاة واحدة بدلاً من مطاردة الأخطاء عبر كل اختبار. يشرح شرح واجهة برمجة تطبيقات المحاكاة الخاص بنا النهج العام.

هذا الانقسام مهم. تختبر مقابل نقطة النهاية الحية للتحقق من عقد OpenAI، وتقوم بمحاكاتها لتطوير سريع وغير متصل وحتمي. كلاهما يعمل من نفس مشروع Apidog.

أسئلة مكررة

هل ستحل Responses API محل Chat Completions؟

ليس بالقوة. تصف OpenAI واجهة برمجة تطبيقات الاستجابات بأنها تطور لإكمال المحادثة وتوصي بها للمشاريع الجديدة، لكن Chat Completions تظل مدعومة ولم يتم الإعلان عن تاريخ إيقافها. يمكنك ترحيل تدفق واحد في كل مرة. أما Assistants API فهو الذي يتم إيقافه، مع تاريخ توقف في عام 2026.

ما الفرق بين `store` و `previous_response_id`؟

تتحكم store فيما إذا كانت OpenAI تحفظ كائن الاستجابة على الإطلاق (يكون افتراضيًا صحيحًا ويحتفظ به لمدة 30 يومًا). previous_response_id هو كيف تربط طلبًا جديدًا بطلب مخزن حتى يواصل النموذج المحادثة على جانب الخادم. تستخدمهما معًا لسلاسل المحادثات ذات الحالة، وتقوم بإيقاف store عندما تريد سلوكًا بدون حالة.

ما هي النماذج التي تدعم Responses API؟

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

هل يمكنني اختبار الأدوات المدمجة دون كتابة تعليمات برمجية؟

نعم. أضف مصفوفة tools إلى جسم JSON في Apidog، وأرسل الطلب، وتأكد من ظهور عنصر استدعاء الأداة المطابق (مثل web_search_call) في مصفوفة output. أنت تتحقق من سلوك OpenAI عبر HTTP، لذا لا يلزم وجود حزمة SDK. لاختبار استدعاءات أدوات الوكيل بشكل أوسع، راجع كيفية إنشاء مجموعات اختبار API من مواصفات OpenAPI.

الخلاصة

لديك الآن الحلقة الكاملة: نقطة نهاية واحدة، POST /v1/responses، تتعامل مع النص، والأدوات المستضافة، وحالة المحادثة من جانب الخادم. أرسل طلبًا، واقرأ output المتداخل، وأضف مصفوفة tools عندما تحتاج إلى بحث أو تنفيذ تعليمات برمجية، واربط previous_response_id للحفاظ على استمرارية السلسلة. نظرًا لاختلاف الشكل عن Chat Completions، فإن الخطوة الأكثر أمانًا هي التحقق من العقد بنفسك بدلاً من الاعتماد على ذاكرتك للواجهة البرمجية الأقدم.

وهنا يأتي دور Apidog. قم ببناء الطلب، وتخزين مفتاحك كمتغير بيئة، والتأكد من حقول output المتداخلة، ومحاكاة الاستجابة للعمل دون اتصال بالإنترنت، كل ذلك في مشروع واحد. قم بتنزيل Apidog ووجه اختبارًا إلى /v1/responses لترى بالضبط ما يتلقاه تكاملك. يمكنك القيام بالإعداد بالكامل في Apidog دون كتابة سطر واحد من تعليمات الاختبار.

زر