تحويل النص إلى كلام
أرسل النص عبر اتصال WebSocket واستقبل الصوت على شكل أجزاء. ابدأ بمثال كامل يحفظ ملف WAV قابلاً للتشغيل.
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniهل أنت جديد في واجهات برمجة تطبيقات الكلام؟ ابدأ بهذه المصطلحات الأربعة.
- WebSocket
- اتصال يظل مفتوحًا حتى يتمكن البرنامج والخادم من تبادل الرسائل في كلا الاتجاهين.
- نموذج
- المحرك الذي يقوم بالمهمة. استخدم نموذج تحويل النص إلى كلام للتحدث ونموذج ASR للنسخ؛ انسخ المعرف العام الدقيق الخاص به.
- صوت
- الصوت المستخدم للتوليف. اختر voice_id من كتالوج الطراز المحدد؛ الاعتراف لا يحتاج إلى صوت.
- مفتاح API
- بيانات اعتماد الوصول الخاصة بك، التي تم إنشاؤها في وحدة التحكم. يتم إدخاله في رأس Authorization عند فتح الاتصال.
اتصالك الأول
اختر طريقة التكامل والبيئة الخاصة بك، ثم اتبع الخطوات أدناه.
قم بإعداد مجلد وتثبيت المكتبة
استخدم Python 3.10 أو الأحدث. افتح محطة طرفية في مجلد فارغ وقم بتثبيت OpenAI SDK الرسمي. يتصل ببوابة الكلام عبر WebSocket؛ تم اختبار المثال مع الإصدار أدناه. تحميل ↗
python3 -m venv .venv .venv/bin/python -m pip install "openai[realtime]==3.35.1"
قم بتعيين مفتاح API الخاص بك
أنشئ مفتاحًا في وحدة التحكم، ثم استبدل YOUR_API_KEY أدناه بمفتاحك الخاص. قم بتشغيل هذا في نفس المحطة كما في المثال. إدارة مفاتيح API ↗
export STARSG_API_KEY="YOUR_API_KEY"
حافظ على خصوصية مفتاحك. هذه أمثلة محلية/خادم، وليست رمز المتصفح. لا تضع مفتاح API الدائم في صفحة ويب أو مستودع عام. يؤدي تشغيل المثال إلى إجراء استدعاء نموذج قابل للفوترة.
احفظ المثال وقم بتشغيله
انسخ المثال الكامل أدناه إلى ملف نص عادي جديد يسمى speech.py في هذا المجلد. احفظه، ثم قم بتشغيل هذا الأمر في نفس المحطة.
.venv/bin/python speech.py
كيف يبدو النجاحتقوم المحطة بطباعة "المحفوظة:" وتقوم بإنشاء ملف الإخراج.wav. افتحه باستخدام مشغل الصوت الخاص بك. للتشغيل مرة أخرى، قم بإعادة تسمية هذا الملف أو إزالته أولاً؛ المثال لن يحل محله.
مثال كامل
انسخ الملف بأكمله. يقوم بالاتصال وتكوين الجلسة وإرسال إدخال واحد وانتظار الانتهاء وإغلاق الاتصال. ولا يقوم بإعادة المحاولة تلقائيًا.
import asyncio
import base64
import json
import os
from pathlib import Path
import wave
from openai import AsyncOpenAI
API_KEY = os.environ["STARSG_API_KEY"]
BASE_URL = "https://api.starsg.ai/v1"
MODEL = "tts-altair-v1-mini"
SESSION = json.loads("{\"type\":\"realtime\",\"output_modalities\":[\"audio\"],\"audio\":{\"output\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000}}}}")
TEXT = "مرحبًا! هذا هو المثال الأول لتوليف الكلام."
OUTPUT = Path("output.wav")
if OUTPUT.exists():
raise FileExistsError("output.wav exists; rename it before running again")
voice = os.environ.get("SPEECH_VOICE")
if voice:
SESSION["audio"]["output"]["voice"] = voice
async def main():
async with AsyncOpenAI(api_key=API_KEY, base_url=BASE_URL,
max_retries=0) as client:
async with client.realtime.connect(model=MODEL) as connection:
async def receive():
event = (await connection.recv()).model_dump()
if event["type"] == "error" or event["type"].endswith(".failed"):
raise RuntimeError(json.dumps(event.get("error", event), ensure_ascii=False))
return event
async def wait_for(kind):
while True:
event = await receive()
if event["type"] == kind:
return event
await wait_for("session.created")
await connection.session.update(session=SESSION)
await wait_for("session.updated")
await connection.conversation.item.create(item={
"type": "message", "role": "user",
"content": [{"type": "input_text", "text": TEXT}]
})
await connection.response.create()
audio = bytearray()
while True:
event = await receive()
if event["type"] == "response.output_audio.delta":
audio.extend(base64.b64decode(event["delta"], validate=True))
elif event["type"] == "response.done":
if event.get("response", {}).get("status") != "completed":
raise RuntimeError("Audio generation did not complete")
if not audio or len(audio) % 2:
raise ValueError("No valid PCM audio received")
with OUTPUT.open("xb") as target:
with wave.open(target, "wb") as wav:
wav.setparams((1, 2, 24000, 0, "NONE", "not compressed"))
wav.writeframes(audio)
print("Saved:", OUTPUT.resolve())
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
يستخدم المثال معرف النموذج العام. يعتمد التوفر على حسابك وبيئتك؛ اختر نموذجًا يدعم هذه المهمة في الوقت الفعلي. عرض النماذج ↗
لاختيار صوت، ابحث عن voice_id في كتالوج الصوت الخاص بهذا الطراز وقم بتعيين SPEECH_VOICE في جهازك الطرفي قبل التشغيل. احذفه لاستخدام الصوت الافتراضي. اسم العرض مثل "Alloy" ليس voice_id. استبدل VOICE_ID أدناه بقيمة من هذا الكتالوج.
export SPEECH_VOICE="VOICE_ID"
تدفق الحدث
كل رسالة هي حدث JSON. إرسال يعني برنامجك → الخادم؛ تلقي يعني الخادم → البرنامج الخاص بك. انتظر session.updated قبل إرسال المدخلات.
- يستلم
session.createdلقد فتح الخادم جلسة. يمكنك الآن إرسال التكوين الخاص به.
- يرسل
session.updateقم بتعيين المهمة وتنسيق الصوت والصوت الاختياري.
- يستلم
session.updatedوافق الخادم على التكوين. الآن أرسل المدخلات.
- يرسل
conversation.item.createأنشئ رسالة مستخدم باستخدام content.type=input_text وcontent.text تحتوي على النص الخاص بك.
- يرسل
response.createاطلب من الخادم إنشاء صوت للنص.
- يستلم
response.output_audio.deltaقم بفك تشفير حقل دلتا Base64 وجمع بايتات PCM بالترتيب. هذه القطع ليست ملفات WAV منفصلة.
- يستلم
response.doneتحقق من اكتمال Response.status، ثم قم بإضافة رأس WAV واحفظ الصوت الذي تم جمعه. الحالات الأخرى هي الفشل.
افحص رسالة session.update
{
"type": "session.update",
"session": {
"type": "realtime",
"output_modalities": [
"audio"
],
"audio": {
"output": {
"format": {
"type": "audio/pcm",
"rate": 24000
}
}
}
}
}مرجع المعلمة
تُظهر الأسماء ذات النقاط المكان الذي ينتمي إليه الحقل في كائن JSON. تنطبق كلمة "مطلوب" أدناه على سير العمل في هذا الدليل. يعتمد الدعم والحدود المتقدمة على الطراز.
الاتصال والمصادقة
modelstringمطلوبمعلمة الاستعلام المطلوبة في WebSocket URL. استخدم معرف النموذج العام الدقيق من كتالوج الوقت الفعلي. طرازات ASR وTTS غير قابلة للتبديل.
مثال / الإعدادtts-altair-v1-miniAuthorizationstringمطلوبرأس الاتصال: Bearer، مسافة واحدة، ثم مفتاح API. استخدم المفتاح للبيئة المستهدفة؛ لا تضعه في URL.
مثال / الإعدادBearer <API_KEY>
الجلسة والمدخلات
session.typestringمطلوباستخدم الوقت الفعلي لجلسة تحويل النص إلى كلام. هذا سير عمل تركيبي، وليس محادثة عامة بين الوكيل الصوتي.
مثال / الإعداد"realtime"session.output_modalitiesstring[]مطلوبطلب إخراج الصوت للتوليف. أرسل هذه المصفوفة في session.update.
مثال / الإعداد["audio"]session.audio.output.formatobjectمطلوبتكوين الصوت: النوع هو الصوت/pcm، والمعدل هو 24000. يستخدم هذا المثال عينات 16 ذات النهاية الصغيرة ذات التوقيع الأحادي: 48,000 بايت في الثانية. لا يتم إرسال رؤوس WAV عبر المقبس.
مثال / الإعداد{"type":"audio/pcm","rate":24000}session.audio.output.voicestringخياريvoice_id اختياري من الكتالوج الصوتي للطراز المحدد. يتم تحديد نطاقه للنموذج. حذفه للخادم الافتراضي؛ لا تستخدم اسم عرض البائع. اضبطه قبل بدء إخراج الصوت.
تصفح الأصواتالافتراضي / المحذوف الصوت الافتراضي للنموذجitem.content[].textstringمطلوبالنص المراد تركيبه، داخل المحادثة.item.create → العنصر → المحتوى. قم بتعيين نوع عنصر المحتوى على input_text، وitem.type للرسالة، وitem.role للمستخدم. حدود النص تعتمد على النموذج.
عناصر تحكم صوتية اختيارية
ابدأ بدون هذه الضوابط. تحقق من output_controls للنموذج قبل إضافتها. تتسبب قيم الحجم أو درجة الصوت غير المدعومة في حدوث خطأ؛ ولا يتم تجاهلهم بصمت. قفل الصوت والسرعة بعد إخراج الصوت الأول؛ يمكن تحديث مستوى الصوت ودرجة الصوت لاحقًا.
session.audio.output.speednumberخياريمضاعف معدل التحدث: 1.0 هي السرعة العادية. تعتمد قيم الحد الأدنى/الحد الأقصى المقبولة على الطراز؛ تحقق من الكتالوج. اضبطه قبل إخراج الصوت الأول.
مثال / الإعداد1.0session.audio.output.options.volumenumber | nullخياريملحق النظام الأساسي في الخيارات: كسب مضاعف، قيمة محايدة 1.0. نطاق البروتوكول هو 0 < حجم الصوت ≥ 10، ولكن يجب أن يدعمه النموذج. يستخدم المحذوف أو الفارغ القيمة المحايدة؛ يتم رفض القيم غير المدعومة.
الافتراضي / المحذوف1.0session.audio.output.options.pitchnumber | nullخياريامتداد المنصة في الخيارات: تغيير درجة الصوت في نصف النغمات، القيمة المحايدة 0. نطاق البروتوكول الخارجي هو −24 إلى 24؛ نموذج قد يسمح أقل. استخدم حدودها المعلنة. يستخدم المحذوف أو الفارغ طبقة صوت محايدة.
الافتراضي / المحذوف0
استكشاف الأخطاء وإصلاحها
اقرأ رسالة الخطأ التي تم إرجاعها أولاً. لا يعني فتح الاتصال أو وصول مقطع صوتي أن الطلب قد اكتمل بنجاح.
لم يتم العثور على الأمر أو الوحدة النمطية مفقودة
قم بتثبيت وقت التشغيل المحدد، وأعد فتح الجهاز الطرفي الخاص بك وقم بتشغيل أوامر الإعداد في مجلد المشروع. بالنسبة إلى Python، استخدم مترجم .venv الموضح أعلاه؛ قم بتثبيت websocket-client، وليس حزمة websocket التي تحمل نفس الاسم. تستخدم أمثلة Node.js حزمة ws وملف .mjs.
401 / 403 أو مفتاح API مفقود
تأكد من تعيين متغير البيئة في هذه المحطة، ومن أنه تم استبدال YOUR_API_KEY، وأن المفتاح ينتمي إلى البيئة المستهدفة. تأكيد الوصول إلى النموذج وحالة الحساب. احتفظ بالمفتاح بعيدًا عن لقطات الشاشة والسجلات.
فشل المصافحة، 404 / 503، أو لم يتم العثور على النموذج
تحقق من اسم مضيف WSS والمنفذ ومسار /v1/realtime ومعرف النموذج العام الدقيق. استخدم كتالوج نماذج الوقت الفعلي للبيئة المستهدفة. لا تتبع إعادة التوجيه إلى HTTP URL غير الآمن. قد يطلب 503 من مشغل الخدمة التحقق من التوفر.
لا يوجد نص أو صوت غير صالح أو تشغيل مشوه
تحقق من 24 كيلوهرتز، وأحادي، وPCM ذو نهاية صغيرة 16 بت، وما لا يقل عن 100 مللي ثانية من الكلام. استخدم أمر التحويل بدلاً من إعادة تسمية الملف. يقوم التعرف بإرسال PCM الخام، وليس رأس WAV. للتوليف، قم بفك تشفير Base64 وانضم إلى قطع PCM قبل إنشاء ملف WAV.
invalid_value أو عنصر تحكم غير معتمد
قم بإزالة إعدادات السرعة ومستوى الصوت ودرجة الصوت الاختيارية، ثم تحقق من output_controls للطراز المحدد. لا تقم بإعادة استخدام voice_id أو الحدود الرقمية لطراز آخر. لا يطبق تحديث الجلسة المرفوض هذا التكوين.
انتهت المهلة أو إغلاق الاتصال قبل الانتهاء
تتوقف الأمثلة بعد ثواني 90. حاول إدخال أقصر وتحقق من الوصول إلى الشبكة. لا تعامل النص الجزئي أو الصوت الجزئي على أنه نجاح. تحقق مما إذا كان الطلب السابق قد تم تشغيله قبل إعادة المحاولة لتجنب المكالمات المتكررة.
Output.wav موجود بالفعل أو أن ملف الإدخال مفقود
قم بتشغيل البرنامج النصي من المجلد الذي يحتوي على الكلام.py أو الكلام.mjs. ضع input.wav (Python) أو input.pcm (Node.js) هناك. أعد تسمية ملفput.wav السابق قبل الإنشاء مرة أخرى. السطر "النهائي:" هو نتيجة التعرف؛ ولا يقوم بإنشاء ملف صوتي.
خلفية البروتوكول: OpenAI WebSockets ↗