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

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

جرّب Apidog اليوم

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

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

قبل كتابة الكود، حدد معرف النموذج الذي ستستخدمه:

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

استخدم الاسم المستعار أثناء التطوير، ثم ثبّت لقطة مؤرخة قبل الإنتاج حتى لا يتغير سلوك الوكيل تلقائيًا بعد تحديث النموذج.

المعرف	ما يشير إليه
gpt-realtime-mini	أحدث لقطة مصغرة مع تحديث تلقائي
gpt-realtime-2.1-mini	الجيل المصغر 2.1
gpt-realtime-mini-2025-12-15	لقطة مثبتة حالية
gpt-realtime-mini-2025-10-06	لقطة مثبتة سابقة

ما الذي يقدمه gpt-realtime-2.1-mini؟

gpt-realtime-2.1-mini هو نموذج كلام إلى كلام. ترسل إليه الصوت، فيرد بصوت طبيعي دون بناء خط أنابيب منفصل للنسخ وTTS. كما يدعم النص، لذلك يمكنك مزج الإدخال المكتوب والإخراج الصوتي داخل الجلسة نفسها.

حسب صفحة النموذج:

الخاصية	القيمة
وسائط الإدخال	نص، صورة، صوت
وسائط الإخراج	نص، صوت
نافذة السياق	32,000 رمز
الحد الأقصى للإخراج	4,096 رمز
الاتصالات	WebRTC, WebSocket, SIP
الأصوات	alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar

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

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

التكلفة

النموذج المصغر أرخص بكثير من النموذج الكامل. الأسعار التالية من صفحة التسعير:

النموذج	إدخال نص	إدخال مخبأ	إدخال صوت	إخراج صوت
gpt-realtime-2.1-mini	$0.60 / 1 مليون	$0.30 / 1 مليون	$10 / 1 مليون	$20 / 1 مليون
gpt-realtime-2.1	$4.00 / 1 مليون	$0.40 / 1 مليون	$32 / 1 مليون	$64 / 1 مليون

إخراج الصوت هو العامل الأكبر في الفاتورة. وكيل يتحدث 35 ثانية في الدقيقة قد يكلف تقريبًا ضعف وكيل يتحدث 15 ثانية في الدقيقة. لتقليل التكلفة، اجعل التعليمات تطلب إجابات قصيرة ومباشرة، وراجع صفحة التسعير الحية قبل بناء التوقعات المالية.

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

قبل البدء، جهّز التالي:

1. مفتاح OpenAI API مع وصول إلى Realtime API، محفوظ في المتغير OPENAI_API_KEY.
2. Node.js 18+.
3. حزمة ws إذا كنت ستستخدم WebSocket الخام.
4. صفحة تعمل عبر HTTPS أو localhost إذا كنت ستستخدم getUserMedia في المتصفح.

لا ترسل مفتاح API الحقيقي إلى المتصفح أبدًا.

تطبيقات المتصفح والجوال يجب أن تستخدم رموزًا مؤقتة قصيرة الأجل.

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

يدعم النموذج ثلاث وسائل نقل. اختر حسب مكان التقاط الصوت وتشغيله.

وسيلة النقل	متى تستخدمها	المصادقة
WebRTC	عندما يلتقط المتصفح أو تطبيق الجوال الصوت ويشغله مباشرة	مفتاح مؤقت للعميل
WebSocket	عندما يتعامل الخادم مع الصوت الخام أو تريد نموذجًا أوليًا سريعًا	مفتاح API من جانب الخادم
SIP	عند ربط نظام هاتف أو اتصالات	مفتاح API

ابدأ عادةً بـ WebSocket للاختبار من الخادم، ثم انتقل إلى WebRTC عند بناء واجهة صوتية حقيقية في المتصفح.

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

نقطة نهاية WebSocket هي:

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

في واجهة GA، استخدم ترويسة Authorization: Bearer فقط. لا تحتاج إلى ترويسة OpenAI-Beta القديمة.

ثبّت الحزمة:

npm install ws

ثم جرّب إدخال نص وإخراج نص دون ميكروفون:

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. تهيئة الجلسة
  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. إضافة رسالة المستخدم
  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "What is an idempotent request?",
        },
      ],
    },
  }));

  // 3. طلب الاستجابة
  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();
  }
});

ws.on("error", console.error);

التسلسل العملي دائمًا:

1. أرسل session.update.
2. أضف مدخلات عبر conversation.item.create.
3. اطلب الرد عبر response.create.
4. استمع إلى أحداث delta.

أهم أحداث الخادم:

الحدث	الاستخدام
session.created / session.updated	تأكيد قبول إعدادات الجلسة
response.output_text.delta	جزء من النص
response.output_audio.delta	جزء صوتي بترميز base64
response.output_audio_transcript.delta	نص لما يقوله النموذج
response.done	انتهاء الجولة

للانتقال إلى الصوت، غيّر output_modalities إلى ["audio"] وأضف إعدادات الصوت في الجلسة.

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

استخدم WebRTC عندما تريد ميكروفونًا وتشغيلًا مباشرًا للصوت في المتصفح. لا تكشف مفتاح API في العميل؛ أنشئ أولًا مفتاحًا مؤقتًا من الخادم.

الخطوة 1: إنشاء مفتاح مؤقت من الخادم

// server.js
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(); // يبدأ عادةً بـ ek_

أرسل value إلى المتصفح. هذا المفتاح قصير العمر ومخصص لجلسة العميل.

الخطوة 2: الاتصال من المتصفح

<audio id="audio" autoplay></audio>

<script type="module">
  // احصل عليه من خادمك
  const EPHEMERAL_KEY = await fetch("/session-token")
    .then((r) => r.text());

  const pc = new RTCPeerConnection();

  // تشغيل صوت النموذج
  pc.ontrack = (event) => {
    document.getElementById("audio").srcObject = event.streams[0];
  };

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

  // قناة بيانات لأحداث Realtime
  const channel = pc.createDataChannel("oai-events");

  channel.onmessage = (event) => {
    console.log("server event:", JSON.parse(event.data));
  };

  channel.onopen = () => {
    channel.send(JSON.stringify({
      type: "session.update",
      session: {
        type: "realtime",
        model: "gpt-realtime-2.1-mini",
        output_modalities: ["audio"],
        instructions: "You are a concise voice assistant. Keep answers short.",
      },
    }));
  };

  // 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(),
  });
</script>

بعد اكتمال الاتصال:

• الميكروفون يرسل الصوت إلى النموذج.
• 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:

1. تعرّف الدوال في الجلسة.
2. النموذج يرسل طلب استدعاء دالة.
3. خادمك ينفذ الدالة.
4. ترسل النتيجة إلى المحادثة.
5. تطلب response.create جديدًا ليكمل النموذج الرد.

إذا أردت فهم المخطط بعمق، راجع استدعاء دوال OpenAI، وللمخرجات الصارمة راجع المخرجات المنظمة.

مثال مبسط لتعريف أداة:

{
  type: "session.update",
  session: {
    type: "realtime",
    model: "gpt-realtime-2.1-mini",
    tools: [
      {
        type: "function",
        name: "lookup_order",
        description: "Look up an order by order ID.",
        parameters: {
          type: "object",
          properties: {
            order_id: {
              type: "string"
            }
          },
          required: ["order_id"]
        }
      }
    ],
    tool_choice: "auto"
  }
}

عند وصول حدث مثل response.function_call_arguments.done:

if (event.type === "response.function_call_arguments.done") {
  const args = JSON.parse(event.arguments);

  const result = await lookupOrder(args.order_id);

  ws.send(JSON.stringify({
    type: "conversation.item.create",
    item: {
      type: "function_call_output",
      call_id: event.call_id,
      output: JSON.stringify(result),
    },
  }));

  ws.send(JSON.stringify({
    type: "response.create",
  }));
}

للوكلاء متعددّي الخطوات، راجع AgentKit من OpenAI.

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

لا تبدأ بتصحيح أخطاء WebRTC داخل تطبيق نصف مكتمل. اختبر كل طبقة منفصلة أولًا باستخدام Apidog.

1. اختبار نقطة إنشاء المفتاح المؤقت

أنشئ طلب REST:

POST https://api.openai.com/v1/realtime/client_secrets

أضف الترويسات:

Authorization: Bearer YOUR_OPENAI_API_KEY
Content-Type: application/json

وأرسل الجسم:

{
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini"
  }
}

إذا حصلت على قيمة تبدأ بـ ek_، فهذا يعني أن المفتاح والصلاحيات يعملان قبل الدخول في تعقيدات WebRTC. نفس الأسلوب ينطبق على اختبار واجهات REST الأخرى مثل واجهة Responses API.

2. اختبار WebSocket يدويًا

افتح عميل WebSocket في Apidog واتصل بـ:

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

أضف الترويسة:

Authorization: Bearer YOUR_OPENAI_API_KEY

ثم أرسل الرسائل بالتسلسل:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "model": "gpt-realtime-2.1-mini",
    "output_modalities": ["text"],
    "instructions": "You are a concise API support agent."
  }
}

{
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "Explain retries in APIs."
      }
    ]
  }
}

{
  "type": "response.create"
}

مشاهدة الأحداث في لوحة قابلة للقراءة تجعل تسلسل Realtime أوضح، ويمكنك حفظ الرسائل كأمثلة للفريق. إذا كنت تستخدم منهجية اختبار API منظمة، فهذا يتكامل مع استراتيجيات اختبار API.

يمكنك تنزيل Apidog إذا أردت تجربة الخطوات عمليًا.

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

لتقليل تكلفة وكيل الصوت:

• اجعل الردود قصيرة: أضف في instructions: "أجب بجملة أو جملتين".
• ثبّت لقطة في الإنتاج: استخدم مثلًا gpt-realtime-mini-2025-12-15 بدل الاسم المستعار إذا أردت سلوكًا ثابتًا.
• استخدم semantic_vad: يقلل المقاطعات الخاطئة والاستجابات الجزئية غير المفيدة.
• حافظ على موجه النظام ثابتًا: الإدخال المخبأ أرخص من الإدخال النصي الجديد.
• أغلق الجلسات الخاملة: لا تترك الاتصالات مفتوحة بلا مستخدم نشط.

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

المشكلة	السبب المحتمل	الإصلاح
401 Unauthorized	مفتاح خاطئ أو مفتاح مؤقت منتهي	أنشئ مفتاحًا مؤقتًا جديدًا لكل جلسة
Model not found	معرف نموذج غير صحيح	استخدم gpt-realtime-2.1-mini وليس gpt-realtime-mini-2.1
لا يوجد صوت في المتصفح	لم تربط pc.ontrack أو الصفحة ليست HTTPS/localhost	اربط التدفق البعيد وتأكد من بيئة آمنة
النموذج يتحدث فوق المستخدم	كشف الدور غير مناسب أو الميكروفون لا يصل	استخدم semantic_vad وتحقق من مسار الميكروفون
أخطاء بسبب ترويسة بيتا	استخدام OpenAI-Beta: realtime=v1 مع GA	أزل الترويسة

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

هل gpt-realtime-2.1-mini هو نفسه gpt-realtime-mini؟

عمليًا نعم، لكن الاستخدام يختلف. gpt-realtime-2.1-mini معرف بإصدار، بينما gpt-realtime-mini اسم مستعار يشير إلى أحدث لقطة مثل gpt-realtime-mini-2025-12-15.

هل أستخدمه للنسخ فقط؟

Realtime API مصممة للمحادثات التفاعلية منخفضة التأخير من الكلام إلى الكلام. للنسخ لمرة واحدة، استخدم نماذج النسخ المخصصة. استخدم gpt-realtime-2.1-mini عندما تحتاج محادثة ثنائية الاتجاه.

هل أحتاج WebRTC أم WebSocket؟

استخدم WebSocket للنماذج الأولية ومسارات الخادم. استخدم WebRTC عندما يكون المتصفح أو تطبيق الجوال هو من يلتقط ويشغل الصوت مباشرة.

ما الصوت المناسب؟

ابدأ بـ marin أو cedar لأنهما الأحدث والأكثر طبيعية ضمن Realtime API. الأصوات الأخرى مثل alloy وshimmer وverse ما زالت متاحة إذا أردت نبرة مختلفة.

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

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

هل يدعم استدعاء الدوال؟

نعم. يمكن لوكيل Realtime استدعاء دوال مثل نماذج الدردشة: البحث عن طلب، التحقق من المخزون، حجز موعد، أو تنفيذ إجراء أثناء المحادثة.

الخطوة التالية

ابدأ بمثال WebSocket النصي للتأكد من صلاحياتك، ثم غيّر output_modalities إلى ["audio"]. بعد ذلك، ابنِ عميل WebRTC للميكروفون والتشغيل المباشر. قبل الإنتاج، اختبر REST وWebSocket في Apidog، ثبّت لقطة نموذج، واجعل تعليمات الوكيل موجزة للتحكم في التكلفة.