كيف تستخدم GPT-Realtime-2.1-mini API

وكلاء الصوت كانوا يحتاجون إلى ثلاثة أجزاء متحركة: تحويل الكلام إلى نص، نموذج لغوي، ثم تحويل النص إلى كلام. كل خطوة كانت تضيف زمن استجابة وتفقد النبرة. واجهة برمجة تطبيقات OpenAI في الوقت الفعلي (Realtime API) تدمج كل ذلك في نموذج واحد من الكلام إلى كلام، وgpt-realtime-2.1-mini هو الطبقة الأرخص والأسرع من هذه الفئة. يستمع إلى الصوت ويفكر ويتحدث مرة أخرى عبر اتصال تدفق واحد.

يوضح لك هذا الدليل كيفية استدعائه من البداية إلى النهاية: أي معرف نموذج تستخدم، وكيفية الاتصال عبر WebSocket و WebRTC، وكيفية تشكيل جلسة، وكيفية اختبار كل ذلك باستخدام Apidog قبل ربطه بتطبيق. كل ما هنا يتوافق مع دليل OpenAI Realtime الرسمي.

أولاً، اختر اسم النموذج الصحيح

تسبب التسمية ارتباكًا للناس، لذا دعنا نوضحها قبل أي شيفرة. هناك معرفان لنفس النموذج المصغر (mini model):

• gpt-realtime-2.1-mini: المعرف ذو الإصدار. هذا ما يظهر في صفحة تسعير OpenAI ويربطك بالجيل 2.1.
• gpt-realtime-mini: الاسم المستعار للعائلة. يشير دائمًا إلى أحدث لقطة (snapshot)، وهي حاليًا gpt-realtime-mini-2025-12-15.

تتيح لك اللقطات (Snapshots) تثبيت السلوك في بيئة الإنتاج:

استخدم الاسم المستعار (alias) أثناء البناء، ثم ثبّت لقطة مؤرخة (dated snapshot) قبل النشر حتى لا يؤدي تحديث النموذج أبدًا إلى تغيير سلوك وكيلك بين عشية وضحاها.

ما يفعله gpt-realtime-2.1-mini

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

إليك ورقة المواصفات من صفحة النموذج:

marin وcedar هما أحدث الأصوات وحصريان لواجهة برمجة تطبيقات Realtime؛ توصي OpenAI بهما للحصول على الإخراج الأكثر طبيعية. الأصوات الأقدم لا تزال تعمل إذا كنت تريد نبرة صوت محددة.

تفاضل طبقة "mini" عمقًا قليلًا في الاستدلال مقابل زمن استجابة أقل وفاتورة أقل بكثير. بالنسبة لمعظم روبوتات الدعم، وسير عمل طلبات الشراء، والواجهات الأمامية الصوتية، فإنه الخيار الافتراضي الصحيح. استخدم النموذج الكامل gpt-realtime-2.1 فقط عندما تتطلب المحادثة استدلالًا أعمق.

ما تكلفته

النموذج المصغر (Mini) يمثل تقريبًا ثلث سعر النموذج الكامل. أسعار الرموز (tokens) من صفحة التسعير:

الصوت يهيمن على الفاتورة، وأكبر عامل مؤثر في التكلفة هو مدى حديث وكيلك. يكلف الوكيل الذي يتحدث 35 ثانية في الدقيقة تقريبًا ضعف الوكيل الذي يتحدث 15 ثانية في الدقيقة. تتراوح التكاليف الفعلية للدقيقة للنموذج المصغر (mini) حوالي 0.06 دولار إلى 0.15 دولار اعتمادًا على الإسهاب، لذا اطلب من نموذجك أن يكون موجزًا في التعليمات وستقلل الفاتورة مباشرة. تتغير الأسعار، لذا تأكد من صفحة التسعير الحية قبل التنبؤ.

المتطلبات الأساسية

1. مفتاح OpenAI API مع إذن الوصول في الوقت الفعلي (Realtime)، يتم تعيينه كـ OPENAI_API_KEY.
2. Node.js 18+ لأمثلة الخادم (حزمة ws لـ WebSocket الخام، أو حزمة openai SDK الرسمية).
3. بالنسبة للصوت في المتصفح، صفحة تُقدم عبر HTTPS أو localhost لكي يعمل getUserMedia.

قاعدة واحدة قبل أن تبدأ العمل في المتصفح: لا ترسل أبدًا مفتاح API الحقيقي الخاص بك إلى العميل. تستخدم تطبيقات المتصفح والجوال رموزًا مؤقتة قصيرة الأجل بدلاً من ذلك. المزيد عن ذلك أدناه.

اختر طريقة الاتصال

النموذج المصغر (mini model) يدعم ثلاث وسائل نقل. اختر حسب مكان وجود صوتك.

يبدأ معظم الناس باستخدام WebSocket لعمل نماذج أولية من جانب الخادم، ثم ينتقلون إلى WebRTC للعميل الحقيقي. دعنا نفعل الاثنين.

بدء سريع 1: WebSocket من خادمك

WebSocket هو أسرع طريقة لرؤية النموذج يستجيب. نقطة النهاية (endpoint) هي عنوان URL واحد مع النموذج في سلسلة الاستعلام (query string):

wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini

نظرًا لأن هذه هي واجهة GA، فإنك تصادق باستخدام ترويسة Authorization: Bearer عادية ولم تعد بحاجة إلى ترويسة OpenAI-Beta القديمة. إليك مثال "hello world" (إدخال نص، إخراج نص) حتى تتمكن من الاختبار بدون ميكروفون:

import WebSocket from "ws";

const url = "wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini";
const ws = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
});

ws.on("open", () => {
  // 1. تهيئة الجلسة (Configure the session)
  ws.send(JSON.stringify({
    type: "session.update",
    session: {
      type: "realtime",
      model: "gpt-realtime-2.1-mini",
      output_modalities: ["text"],
      instructions: "You are a concise API support agent. Keep answers short.",
    },
  }));

  // 2. إضافة رسالة مستخدم (Add a user message)
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [{ type: "input_text", text: "What is an idempotent request?" }],
    },
  }));

  // 3. طلب استجابة (Ask for a response)
  ws.send(JSON.stringify({ type: "response.create" }));
});

ws.on("message", (raw) => {
  const event = JSON.parse(raw.toString());
  if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
  if (event.type === "response.done") ws.close();
});

التدفق دائمًا هو نفسه: تهيئة، إضافة مدخلات، طلب استجابة، الاستماع إلى التغييرات (deltas). أحداث الخادم تُبث مرة أخرى كـ JSON. أهم الأحداث التي تهتم بها:

• session.created / session.updated: تم قبول تهيئتك
• response.output_text.delta: جزء من النص
• response.output_audio.delta: جزء من الصوت بترميز base64
• response.output_audio_transcript.delta: نسخة لما يقوله النموذج
• response.done: انتهت الجولة

للانتقال من النص إلى الصوت، قم بتبديل output_modalities إلى ["audio"] وأضف تهيئة صوتية (القسم التالي). يصل الصوت في أحداث response.output_audio.delta ككتل PCM مشفرة بـ base64 تقوم بفك تشفيرها وتشغيلها.

بدء سريع 2: WebRTC في المتصفح

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

الخطوة 1: إنشاء رمز مؤقت على خادمك. استدعِ نقطة نهاية client-secrets بمفتاحك الحقيقي:

// جانب الخادم (server side)
const r = await fetch("https://api.openai.com/v1/realtime/client_secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    session: { type: "realtime", model: "gpt-realtime-2.1-mini" },
  }),
});
const { value } = await r.json(); // مفتاح مؤقت (ephemeral key)، يبدأ بـ "ek_"

أرسل value إلى المتصفح. تنتهي صلاحيته بسرعة، لذا فإن التسريب منخفض المخاطر.

الخطوة 2: الاتصال من المتصفح باستخدام WebRTC. تقوم بالتقاط الصوت من الميكروفون، وفتح قناة بيانات للأحداث، وتبادل SDP مع نقطة النهاية /v1/realtime/calls:

// جانب المتصفح (browser side): جاء `EPHEMERAL_KEY` من خادمك
const pc = new RTCPeerConnection();

// تشغيل صوت النموذج (play the model's audio)
pc.ontrack = (e) => (document.getElementById("audio").srcObject = e.streams[0]);

// إرسال الميكروفون (send the mic)
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
pc.addTrack(mic.getTracks()[0]);

// تدفق الأحداث عبر قناة بيانات (events flow over a data channel)
const channel = pc.createDataChannel("oai-events");
channel.onmessage = (e) => console.log(JSON.parse(e.data));

// مصافحة SDP (SDP handshake)
const offer = await pc.createOffer();
await pc.setLocalDescription(offer);

const sdpResp = await fetch(
  "https://api.openai.com/v1/realtime/calls?model=gpt-realtime-2.1-mini",
  {
    method: "POST",
    body: offer.sdp,
    headers: {
      Authorization: `Bearer ${EPHEMERAL_KEY}`,
      "Content-Type": "application/sdp",
    },
  }
);
await pc.setRemoteDescription({ type: "answer", sdp: await sdpResp.text() });

بمجرد أن يصبح الاتصال مباشرًا، يستمع النموذج إلى مسار الميكروفون ويتحدث عبر pc.ontrack. يمكنك إرسال التهيئة والنص عبر نفس قناة بيانات oai-events باستخدام أحداث JSON الدقيقة من مثال WebSocket.

تشكيل الجلسة

كائن session هو المكان الذي تتحكم فيه في السلوك. هذه هي النسخة الصوتية الكاملة مما رأيته أعلاه:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    output_modalities: ["audio"],
    instructions: "You are a friendly booking assistant. Confirm details before acting.",
    audio: {
      input: {
        format: { type: "audio/pcm", rate: 24000 },
        turn_detection: { type: "semantic_vad" },
      },
      output: {
        format: { type: "audio/pcm", rate: 24000 },
        voice: "marin",
      },
    },
  },
}

الحقول المهمة:

• instructions: موجه النظام الخاص بك. عيّن الشخصية، والضوابط، و"كن موجزًا" إذا كنت تهتم بالتكلفة.
• output_modalities: ["audio"] لوكيل يتحدث، ["text"] لروبوت يعرض النص فقط.
• audio.output.voice: اختر من بين الأصوات العشرة؛ marin أو cedar تبدوان الأكثر طبيعية.
• audio.input.turn_detection: كيف يقرر النموذج أنك توقفت عن الكلام. semantic_vad ينتظر وقفة طبيعية في المعنى؛ server_vad يعمل عند الصمت. الكشف الدلالي يقطع المحادثة بشكل أقل ويمنح إحساسًا أكثر سلاسة.

غيّر أي حقل في منتصف المكالمة عن طريق إرسال session.update آخر. لا يلزم إعادة الاتصال.

إضافة أدوات ليتمكن الوكيل من التصرف

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

صرح بالأدوات داخل الجلسة، ثم تعامل مع حدث response.function_call_arguments.done، قم بتشغيل التعليمات البرمجية الخاصة بك، وانشر conversation.item.create بالنتيجة قبل response.create التالي. لأي شيء أكثر تعقيدًا من بضع دوال، يوفر لك AgentKit من OpenAI طريقة أعلى مستوى لتنسيق وكلاء الصوت متعددي الخطوات.

اختبر نقاط النهاية باستخدام Apidog قبل البناء

لا ترغب في تصحيح أخطاء استدعاء REST ومصافحة WebSocket بقراءة سجلات الكونسول في تطبيق نصف مبني. اختبر الأجزاء بشكل منفصل أولاً. هذا هو المكان الذي يكتسب فيه Apidog مكانته في سير عمل الوقت الفعلي (realtime).

هناك شيئان يستحقان التحقق قبل كتابة أي شيفرة للعميل:

1. نقطة نهاية الرمز (token endpoint). POST https://api.openai.com/v1/realtime/client_secrets هي استدعاء REST عادي. أنشئ طلبًا في Apidog، أضف ترويسة Authorization: Bearer الخاصة بك، ضع نص JSON مع معرف النموذج الخاص بك، وأرسله. سترى رمز ek_ وتاريخ انتهائه فورًا، لذا ستعرف أن مفتاحك والوصول إلى حسابك جيدان حتى قبل دخول WebRTC في الصورة. إنه نفس النهج الذي ستستخدمه لاختبار أي من واجهات REST الخاصة بـ OpenAI، مثل واجهة برمجة تطبيقات الاستجابات (Responses API).
2. تدفق رسائل WebSocket. يحتوي Apidog على عميل WebSocket، لذا يمكنك فتح اتصال بـ wss://api.openai.com/v1/realtime?model=gpt-realtime-2.1-mini، إضافة ترويسة المصادقة، وإرسال رسائل session.update، وconversation.item.create، وresponse.create يدويًا واحدة تلو الأخرى. مشاهدة أحداث الخادم وهي تعود في لوحة قابلة للقراءة يجعل تسلسل الأحداث واضحًا، ويمكنك حفظ الرسائل كأمثلة لفريقك. إذا كنت تعتمد بالفعل على استراتيجيات قوية لاختبار API، فهذا يتناسب تمامًا.

اختبار طبقة النقل بمفردها يعني أنه عندما يتعطل شيء ما في التطبيق، فإنك تعلم بالفعل أنه ليس عقد API. قم بتنزيل Apidog إذا كنت ترغب في المتابعة.

تحكم في الفاتورة

إخراج الصوت هو الجزء المكلف، لذا فإن بعض العادات تؤتي ثمارها:

• اطلب من النموذج أن يكون موجزًا. "اجعل الإجابات من جملة أو اثنتين" في التعليمات يقلل مباشرة من رموز إخراج الصوت.
• ثبّت لقطة (snapshot) في بيئة الإنتاج. gpt-realtime-mini-2025-12-15 لن يتغير؛ بينما الاسم المستعار gpt-realtime-mini قد يتغير.
• استخدم semantic_vad. قلة الانقطاعات الخاطئة تعني إهدارًا أقل للاستجابات الجزئية التي تدفع ثمنها.
• تخزين موجه النظام الخاص بك مؤقتًا. الإدخال المخزن مؤقتًا يكلف 0.30 دولار لكل مليون مقابل 0.60 دولار للإدخال النصي الجديد، لذا فإن كتلة التعليمات المستقرة تكون أرخص في كل دورة.
• إغلاق الجلسات الخاملة. الاتصال المفتوح مع مستخدم غير نشط لا يزال يمثل جلسة قد يتم محاسبتك عليها.

الأخطاء الشائعة والإصلاحات

• 401 غير مصرح به (Unauthorized): المفتاح خاطئ، أو أرسلت رمزًا مؤقتًا منتهي الصلاحية. الرموز المؤقتة مصممة لتكون قصيرة الأجل؛ قم بإنشاء رمز جديد لكل جلسة.
• لم يتم العثور على النموذج (Model not found): تحقق من المعرف الدقيق. إنه gpt-realtime-2.1-mini، وليس gpt-realtime-mini-2.1.
• لا يوجد صوت في المتصفح (No audio in the browser): ربما لم تقم بإرفاق التدفق البعيد في pc.ontrack، أو أن الصفحة ليست على HTTPS/localhost لذلك لم يتم فتح الميكروفون أبدًا.
• النموذج لا يتوقف عن التحدث فوق المستخدم (The model won’t stop talking over the user): قم بتبديل turn_detection إلى semantic_vad وتأكد من أن مسار الميكروفون يصل إلى الاتصال.
• إرسال ترويسة البيتا (Sending the beta header): نقطة نهاية GA لا تريد OpenAI-Beta: realtime=v1. قم بإزالته.

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

• هل gpt-realtime-2.1-mini هو نفسه gpt-realtime-mini؟ فعليًا نعم. gpt-realtime-2.1-mini هو المعرف ذو الإصدار، وgpt-realtime-mini هو الاسم المستعار الذي يشير إلى أحدث لقطة (gpt-realtime-mini-2025-12-15). استخدم الاسم المستعار للبناء، وثبت اللقطة عند النشر.
• هل يمكنني استخدامه للنسخ العادي بدلاً من وكيل صوتي؟ تم بناء واجهة برمجة تطبيقات Realtime للمحادثات التفاعلية من الكلام إلى الكلام. للنسخ لمرة واحدة، نماذج النسخ المخصصة من OpenAI هي الأنسب. استخدم النموذج المصغر (mini) في الوقت الفعلي عندما تحتاج إلى محادثة ثنائية الاتجاه بزمن استجابة منخفض.
• هل أحتاج إلى WebRTC، أم أن WebSocket كافٍ؟ WebSocket كافٍ لمسارات عمل جانب الخادم والنماذج الأولية السريعة. استخدم WebRTC عندما يقوم متصفح أو تطبيق جوال بالتقاط وتشغيل الصوت مباشرة، لأنه يتعامل مع تدفق الوسائط والاضطراب نيابة عنك.
• ما الصوت الذي يجب أن أختاره؟ marin وcedar هما الأحدث والأكثر طبيعية، وهما حصريان لواجهة برمجة تطبيقات Realtime. الأصوات الثمانية الأخرى (alloy, ash, ballad, coral, echo, sage, shimmer, verse) لا تزال تعمل إذا كنت تريد صوتًا معينًا.
• كيف تتم الفوترة؟ لكل رمز (token)، مقسمة حسب الوسائط. للنموذج المصغر (mini): 0.60 دولار لكل مليون إدخال نصي، 10 دولارات لكل مليون إدخال صوتي، و 20 دولارًا لكل مليون إخراج صوتي. إخراج الصوت هو التكلفة المهيمنة، لذا الإسهاب هو عاملك الرئيسي.
• هل يمكنه استدعاء الدوال مثل نماذج الدردشة؟ نعم. يستخدم Realtime نفس عقد استدعاء الدوال، لذا يمكن لوكيل صوتي البحث عن الطلبات، أو التحقق من المخزون، أو تفعيل الإجراءات في منتصف المحادثة.

إلى أين نذهب بعد ذلك

لديك الآن الحلقة الكاملة: معرف النموذج الصحيح، نموذج WebSocket الأولي، عميل متصفح WebRTC، تهيئة الجلسة، الأدوات، وطريقة لاختبار كل جزء في Apidog قبل أن يصل إلى الإنتاج. ابدأ بمثال WebSocket للنص فقط لتأكيد الوصول، قم بتبديل output_modalities إلى الصوت، ثم انتقل إلى WebRTC عندما تكون جاهزًا لميكروفون حقيقي. ثبت لقطة (snapshot)، اطلب من النموذج أن يكون موجزًا، وسيكون لديك وكيل صوتي بزمن استجابة منخفض لن يفاجئك في الفاتورة.