اتصل بـ Grok Voice 3.0 باستخدام Python، وأنشئ ردًا منطوقًا، وأرسل الصوت، وأضف الأدوات، واستكشف الأخطاء الشائعة في واجهة برمجة التطبيقات في الوقت الفعلي وأصلحها.
Grok Voice 3.0 هو نموذج تحويل الكلام إلى كلام الآني من xAI، صدر في 14 أكتوبر 2026. اسم نموذج واجهة البرمجة هو grok-voice-3.0؛ واعتبارًا من 3 نوفمبر 2026، grok-voice-latest points to this version. يذكر إعلان الإطلاق تكلفة الجلسات الصوتية بـ 0.08 دولار للدقيقة (4.80 دولار للساعة). يجمع بين المحادثة، والتعامل مع المقاطعات، واستخدام الأدوات لمساعدي الصوت ودعم العملاء. باستخدام Python أساسي، ومفتاح xAI API، ومكتبة websockets، يمكنك إرسال مطالبة وحفظ رد منطوق. ابدأ بالمثال أدناه، ثم أضف الصوت المسجّل، وبث الميكروفون الحي، وأدوات الأعمال مع نمو تطبيقك.
أهم النقاط
يتم تبادل الكلام والنص في الزمن الحقيقي عبر Grok Voice 3.0. يرسل تطبيقك ويتلقى أحداث الجلسة عبر WebSocket طوال المحادثة.
تمت المراجعة للوضوح ودقة المصدر ومصطلحات API الحالية.
يمكن أن يكون اختبارك الأول دورة نص-إلى-صوت واحدة. يُعد الرد القابل للتشغيل تأكيدًا على نجاح المصادقة وتوليد الصوت قبل إضافة الميكروفون.
يتطلب إدخال الصوت تنسيقًا مطابقًا وحدًا واضحًا للدور. يمكن لتطبيقك إرسال صوت PCM مسجّل مع إتمام يدوي للدور أو بث صوت الميكروفون مع كشف الصوت على الخادم.
يتحكم تطبيقك في إجراءات الأعمال. يتحقق من صحة وسيطات الدوال وصلاحيات المستخدم، وينفّذ الإجراء الموافق عليه، ويعيد النتيجة كي يواصل وكيل الصوت.
تستخدم تطبيقات المتصفح والجوّال بيانات اعتماد قصيرة العمر. يحتفظ خادمك بمفتاح API الدائم ويصدر رموزًا مؤقتة لاتصالات العملاء.
ما هو Grok Voice 3.0؟
Grok Voice 3.0 هو نموذج محادثة صوتية آني طوّرته xAI ويعمل تحت علامة SpaceX Super Intelligence. يقبل إدخالًا صوتيًا أو نصيًا ويمكنه إرجاع الصوت والنص ضمن جلسة مستمرة. النموذج مُحسَّن لحالات استخدام وكلاء الصوت، وليس بديلاً مباشرًا عن نماذج Grok النصية العامة.
تسلسل المساعدات الصوتية التقليدية يجمع عادةً بين التعرف على الكلام ونموذج لغوي وتوليد الكلام. بدلاً من ذلك، يوفّر Grok Voice جلسة كلام-إلى-كلام مع سلوك محادثي مدمج ودعم للأدوات. قد يبسّط ذلك طبقة الأوركسترا لدى المطوّر، إلا أن التطبيقات ما تزال بحاجة إلى التقاط الصوت ونقله والتفويض وتكامل الأعمال والمراقبة.
تحدّد وصف نموذج Grok Voice 3.0 النص والصوت كوسائط الإدخال والإخراج. في هذا الدليل، نقطة التحقق المفيدة الأولى هي رد قابل للتشغيل من سكربت Python على الخادم.
الميزات والقدرات الرئيسية لـ Grok Voice 3.0
إجراء محادثة مباشرة: تبادل الكلام والنص عبر WebSocket طوال الجلسة.
التعامل مع المقاطعات: استخدام كشف الصوت على الخادم وإيقاف التشغيل المصفوف عندما يبدأ المتصل بالكلام.
استخدام أدوات الأعمال: ربط دوالك الخاصة لمهام مثل الاستعلام عن الطلبات والجدولة.
هذه نتائج اختبارات منشورة، وليست ضمانات لنشر تطبيقك. اختبر لهجاتك وظروف الضوضاء وأدواتك ومسارات التصعيد قبل استخدام الوكيل مع العملاء.
ما الذي تحتاجه قبل استدعاء واجهة Grok Voice 3.0؟
أنشئ حسابًا أو سجّل الدخول في xAI Console، وأنشئ مفتاح API، وتحقق من أن حسابك لديه صلاحية الوصول والرصيد المتاح للاستخدام. استخدم طرفية محلية أو خادمًا موثوقًا لمثال Python.
Python 3.11 أو أحدث ووجود pip في البيئة نفسها.
مفتاح xAI API صالح مخزّن باسم XAI_API_KEY.
اتصال شبكة يسمح باتصالات WebSocket الآمنة الصادرة.
مشغّل وسائط لفتح ملف WAV المُنشأ.
أنشئ المفتاح في xAI Console. خزّنه في متغير بيئة بدلًا من تضمينه مباشرة في التطبيق.
عيّن مفتاح API لجلسة Bash الحالية.
export XAI_API_KEY="your_xai_api_key"
على Windows PowerShell:
عيّن مفتاح API لجلسة PowerShell الحالية.
$env:XAI_API_KEY="your_xai_api_key"
ثبّت عميل WebSocket في بيئة Python لديك.
python -m pip install "websockets>=14,<18"
نفّذ الأوامر المتبقية في الجلسة الطرفية نفسها. إذا كنت تستخدم بيئة افتراضية، فعّلتها قبل تثبيت الحزمة.
كيفية استخدام واجهة Grok Voice 3.0 مع Python
تستخدم واجهة الزمن الحقيقي اتصال WebSocket. بخلاف إكمالات الدردشة النصية العادية، تتبادل هذه الواجهة أحداث الجلسة المستمرة وتبث مقاطع الصوت أثناء تقدم المحادثة.
الخطوة 1: اختر نموذجًا ثابتًا واضبط الجلسة
تقبل الواجهة اسم نموذج مُعرَّفًا بالإصدار في عنوان WebSocket. يستخدم المثال grok-voice-3.0 كي يكون الإصدار المطلوب صريحًا. يضبط حدث session.update الصوت وتنسيق الصوت والتعامل اليدوي مع الأدوار؛ انتظر session.updated قبل إرسال المطالبة.
الخطوة 2: أرسل نصًا واجمع الرد المنطوق
احفظ السكربت التالي باسم grok_voice_demo.py. يرسل مطالبة نصية واحدة، ويجمع مقاطع صوت مشفّرة بـ base64، ويكتب ملف WAV أحادي القناة، 24 كيلوهرتز، PCM بعمق 16-بت. كما يتوقف عند أخطاء الواجهة، أو إكمال غير ناجح، أو رد لا ينتج عنه صوت.
أنشئ ردًا منطوقًا واحدًا من مطالبة نصية واحفظه كملف WAV.
import asyncio, base64, json, os, wave
import websockets
SAMPLE_RATE = 24000
async def receive_event(ws):
event = json.loads(await asyncio.wait_for(ws.recv(), 60))
if event.get("type") == "error":
raise RuntimeError(event)
return event
async def main():
url = "wss://api.x.ai/v1/realtime?model=grok-voice-3.0"
headers = {"Authorization": f"Bearer {os.environ['XAI_API_KEY']}"}
async with websockets.connect(url, additional_headers=headers) as ws:
await ws.send(json.dumps({"type": "session.update", "session": {
"voice": "eve", "turn_detection": {"type": None},
"audio": {
"input": {"format": {"type": "audio/pcm", "rate": SAMPLE_RATE}},
"output": {"format": {"type": "audio/pcm", "rate": SAMPLE_RATE},
"transport": "json"}}}}))
async with asyncio.timeout(30):
while (await receive_event(ws)).get("type") != "session.updated":
pass
await ws.send(json.dumps({"type": "conversation.item.create", "item": {
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": "اشرح Grok Voice 3.0 بإيجاز."}]}}))
await ws.send(json.dumps({"type": "response.create"}))
chunks = []
async with asyncio.timeout(120):
while True:
event = await receive_event(ws)
if event["type"] in ("response.output_audio.delta", "response.audio.delta"):
chunks.append(base64.b64decode(event["delta"]))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError(event)
break
if not chunks:
raise RuntimeError("لم يتضمن الرد أي صوت.")
with wave.open("grok_response.wav", "wb") as wav:
wav.setparams((1, 2, SAMPLE_RATE, 0, "NONE", "not compressed"))
wav.writeframes(b"".join(chunks))
print("تم حفظ grok_response.wav")
asyncio.run(main())
الخطوة 3: شغّل السكربت وتحقق من النتيجة
شغّل مثال الصوت في Python.
python grok_voice_demo.py
بعد استجابة ناجحة، ستظهر رسالة تم حفظ grok_response.wav. افتح ذلك الملف في مشغّل وسائط وتحقق من أنك تسمع ردًا كاملًا بسرعة طبيعية. يشير فقدان الملف أو عدم قابليته للتشغيل إلى ضرورة فحص الأحداث المرجعة وتكوين الصوت قبل إضافة مزيد من الميزات.
يراجع مرجع أحداث الزمن الحقيقي إقرار الجلسة ودورة حياة الاستجابة المستخدمة هنا. ينتظر السكربت دورة كاملة قبل كتابة الملف؛ ينبغي لتطبيق الصوت التفاعلي تشغيل المقاطع فور وصولها.
كيف تُرسل صوتًا إلى Grok Voice 3.0؟
صوت مسجّل مع إتمام يدوي للدور
يستخدم هذا المثال ملف WAV أحادي القناة، 24 كيلوهرتز، PCM بعمق 16-بت. يدعم Grok Voice 3.0 معدلات عيّنة PCM أخرى، وμ-law، وA-law، وOpus. يجب أن يطابق التنسيق الفعلي إعداد session.update. استبدل فقط كتلة conversation.item.create في السكربت السابق بالمقتطف أدناه. حافظ على استدعاء response.create الموجود وحلقة الاستقبال الحالية.
استبدل كتلة الرسالة النصية برفع صوت مسجّل داخل الدالة main().
with wave.open("request.wav", "rb") as source:
if (
source.getnchannels() != 1
or source.getsampwidth() != 2
or source.getframerate() != SAMPLE_RATE
or source.getcomptype() != "NONE"
):
raise ValueError("استخدم صوت WAV أحادي القناة، 24 كيلوهرتز، 16-بت PCM.")
pcm = source.readframes(source.getnframes())
if len(pcm) < SAMPLE_RATE * 2 // 10:
raise ValueError("استخدم تسجيلًا صوتيًا أطول من 100 مللي ثانية.")
for offset in range(0, len(pcm), 4800):
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[offset:offset + 4800]).decode("ascii"),
}))
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
while (await receive_event(ws)).get("type") != "input_audio_buffer.committed":
pass
احفظ هذا الاستبدال بالمستوى نفسه من الإزاحة داخل سياق WebSocket. يرسل هذا المقتطف عينات PCM الخام من ملف WAV، وليس ترويسة الحاوية. يحدّد السكربت الأول بوضوح الوضع اليدوي للأدوار، لذا فإن اعتماد المخزن المؤقت ثم طلب الاستجابة هما إجراءان منفصلان.
التقاط الميكروفون الحي والتشغيل الفوري
لإجراء محادثة تفاعلية، التقط الصوت باستمرار، وحوّله إلى تنسيق الإدخال المضبوط، وأرسل مقاطع قصيرة بينما تتعامل حلقة استقبال منفصلة مع الردود. اختر server_vad لاكتشاف تلقائي للدور بدلًا من الوضع اليدوي المستخدم في مثال الملف المسجّل. تجنّب إضافة response.create ثانية عندما يكون الخادم بالفعل بصدد إنشاء الرد.
عند حدوث مقاطعة، أوقِف تشغيل صوت المساعد المصفوف بسرعة. لا يؤدي الإلغاء عبر الشبكة وحده إلى إزالة الصوت المخزّن مسبقًا في تطبيقك. أبقِ قائمة التشغيل صغيرة وتتبع مقدار الصوت الذي استمع إليه المستخدم فعليًا حتى يحافظ تطبيقك على اتساق حالة المحادثة.
كيف تُضيف أدوات إلى وكيل Grok Voice 3.0؟
يمكن للتطبيقات إتاحة أدوات مثل الاستعلام عن الطلبات أو الجدولة أو التحقق من الحساب. يستطيع الوكيل تفسير طلب منطوق معقد، واستدعاء دالة مخوّلة، واستخدام النتيجة للمتابعة. يكون هذا مفيدًا بشكل خاص عندما يطلب العميل عدة تغييرات مترابطة في مكالمة واحدة.
تدعم الواجهة دوالًا مخصّصة وأدوات تُدار على الخادم. بالنسبة للدالة المخصّصة، يطبّق تطبيقك الإجراء؛ إن تعريف الأداة لا يربط النموذج بقاعدة بياناتك بحد ذاته.
أعلن عن اسم الدالة ووصفها ومخطط وسائط JSON في session.tools.
تعامل مع response.function_call_arguments.done، وحلّل الوسائط، وتحقق من صلاحية المتصل قبل تنفيذ الدالة.
أعد النتيجة عبر حدث conversation.item.create مع item.type مضبوطًا إلى function_call_output ومع call_id المطابق.
أرسل response.create بعد إرسال نتائج الدوال المطلوبة. إذا وردت عدة استدعاءات معًا، أعِد كل نتائجها قبل طلب متابعة النموذج.
ابدأ بأداة قراءة فقط، مثل التحقق من حالة تسليم الطلب. بالنسبة للإجراءات التي تغيّر الحجوزات أو تصدر ردّيات أو تُتمّ طلبات، طبّق فحوص الهوية والتأكيد والحماية من الطلبات المكررة في التطبيق.
كيفية استخدام Grok Voice 3.0 في تطبيقات المتصفح والجوّال
استخدم بيانات اعتماد مؤقتة لاتصالات الطرف العميل. يطلب خادمك رمزًا قصير العمر باستخدام مفتاح API الدائم، ثم يمرّر الرمز إلى العميل. صادِق الطلبات إلى نقطة نهاية الرموز الخاصة بك وطبّق حدود استخدام حتى لا تصبح بوابة غير مقيّدة.
اجعل موافقة الميكروفون، وعناصر التحكم بالتسجيل، وحالة الاتصال مرئية في الواجهة. تعامل صراحة مع فقدان الاتصال: أوقِف التشغيل القديم، وأعلم المستخدم بأن الاتصال قيد الاستعادة، وتجنب إعادة تنفيذ إجراءات قد تكون اكتملت بالفعل.
كيفية استكشاف أخطاء واجهة Grok Voice 3.0 الشائعة وإصلاحها
فشل المصادقة: تأكد من تعيين XAI_API_KEY في الطرفية التي تشغّل السكربت وأن المفتاح يعود إلى حساب لديه صلاحية الوصول. لا تلصق المفتاح في السجلات أو رسائل الدعم.
معاملات غير متوقعة لمكتبة العميل: تحقق من أن pip ثبّت إصدار websockets المطلوب في بيئة Python التي تُشغّل فيها السكربت.
لا يوجد خرج صوت: افحص أحداث الخطأ وresponse.done، وتأكد من أن session.updated أقرّ التكوين، وتحقق من طلب استجابة لوضع الدور اليدوي.
تشغيل مشوّه: قارن البايتات الفعلية مع برنامج الترميز ومعدل العيّنة وعدد القنوات وترويسة WAV المضبوطة. إعادة تسمية ملف MP3 إلى WAV لا تؤدي إلى تحويله.
مهلة: تحقق من وصول الشبكة وحالة الخدمة، ثم افحص آخر حدث ناجح. أعد محاولة الاتصال الفاشل بشكل منفصل عن أي إجراء أعمال قد يكون نُفّذ بالفعل.
ما الميزانية المتوقعة لاستدعاءات واجهة Grok Voice 3.0؟
يمكن أن تولّد الجلسات الصوتية والتكاملات المخصّصة رسومًا منفصلة. بالنسبة لهذا الدليل، الأسعار المنشورة ذات الصلة هي جلسة الزمن الحقيقي والمدخلات النصية؛ خدمات النسخ والتوليد الصوتي المستقلة هي خدمات منفصلة.
جلسة كلام-إلى-كلام: 0.08 دولار لكل دقيقة، أي ما يعادل 4.80 دولار للساعة.
إدخال نصي أثناء جلسة صوتية: 0.004 دولار لكل إدخال نصي.
تم التحقق من الأسعار في 29 أكتوبر 2026. راجع صفحة التسعير الرسمية للاطلاع على الرسوم الحالية.
على سبيل المثال، 500 دقيقة جلسة قابلة للفوترة تقابل 40 دولارًا كرسوم صوت أساسية. لا يتضمن هذا التقدير المدخلات النصية أو الأدوات الاختيارية أو الاتصالات الهاتفية أو بُنىك التحتية. ابدأ بجلسات اختبار قصيرة وأغلق الاتصالات الخاملة عند انتهاء المحادثة.
الخلاصة
ابدأ بدورة كاملة واحدة لواجهة Grok Voice 3.0: الاتصال، ضبط الجلسة، إرسال مطالبة، استلام الصوت، وتشغيل النتيجة. بعد نجاح هذا المسار، أضف الكلام المسجّل، ثم ابنِ التقاط الميكروفون والبثّ أثناء التشغيل حوله. أدخل أدوات الأعمال فقط بعد أن تصبح مسارات المحادثة ومعالجة الأخطاء موثوقة.
