وثائق API

WebSocketالأحداث المتوافقة مع OpenAI

تحويل النص إلى كلام

أرسل النص عبر اتصال WebSocket واستقبل الصوت على شكل أجزاء. ابدأ بمثال كامل يحفظ ملف WAV قابلاً للتشغيل.

معرف النموذج
النص فيمخرج الصوت
WSSwss://api.starsg.ai/v1/realtime?model=tts-altair-v1-mini
هل أنت جديد في واجهات برمجة تطبيقات الكلام؟ ابدأ بهذه المصطلحات الأربعة.
WebSocket
اتصال يظل مفتوحًا حتى يتمكن البرنامج والخادم من تبادل الرسائل في كلا الاتجاهين.
نموذج
المحرك الذي يقوم بالمهمة. استخدم نموذج تحويل النص إلى كلام للتحدث ونموذج ASR للنسخ؛ انسخ المعرف العام الدقيق الخاص به.
صوت
الصوت المستخدم للتوليف. اختر voice_id من كتالوج الطراز المحدد؛ الاعتراف لا يحتاج إلى صوت.
مفتاح API
بيانات اعتماد الوصول الخاصة بك، التي تم إنشاؤها في وحدة التحكم. يتم إدخاله في رأس Authorization عند فتح الاتصال.

اتصالك الأول

اختر طريقة التكامل والبيئة الخاصة بك، ثم اتبع الخطوات أدناه.

  1. قم بإعداد مجلد وتثبيت المكتبة

    استخدم Python 3.10 أو الأحدث. افتح محطة طرفية في مجلد فارغ وقم بتثبيت OpenAI SDK الرسمي. يتصل ببوابة الكلام عبر WebSocket؛ تم اختبار المثال مع الإصدار أدناه. تحميل ↗

    bash
    python3 -m venv .venv
    .venv/bin/python -m pip install "openai[realtime]==3.35.1"
  2. قم بتعيين مفتاح API الخاص بك

    أنشئ مفتاحًا في وحدة التحكم، ثم استبدل YOUR_API_KEY أدناه بمفتاحك الخاص. قم بتشغيل هذا في نفس المحطة كما في المثال. إدارة مفاتيح API ↗

    bash
    export STARSG_API_KEY="YOUR_API_KEY"

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

  3. احفظ المثال وقم بتشغيله

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

    bash
    .venv/bin/python speech.py
    كيف يبدو النجاح

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

مثال كامل

انسخ الملف بأكمله. يقوم بالاتصال وتكوين الجلسة وإرسال إدخال واحد وانتظار الانتهاء وإغلاق الاتصال. ولا يقوم بإعادة المحاولة تلقائيًا.

python
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 أدناه بقيمة من هذا الكتالوج.

bash
export SPEECH_VOICE="VOICE_ID"

تدفق الحدث

كل رسالة هي حدث JSON. إرسال يعني برنامجك → الخادم؛ تلقي يعني الخادم → البرنامج الخاص بك. انتظر session.updated قبل إرسال المدخلات.

  1. يستلم
    session.created

    لقد فتح الخادم جلسة. يمكنك الآن إرسال التكوين الخاص به.

  2. يرسل
    session.update

    قم بتعيين المهمة وتنسيق الصوت والصوت الاختياري.

  3. يستلم
    session.updated

    وافق الخادم على التكوين. الآن أرسل المدخلات.

  4. يرسل
    conversation.item.create

    أنشئ رسالة مستخدم باستخدام content.type=input_text وcontent.text تحتوي على النص الخاص بك.

  5. يرسل
    response.create

    اطلب من الخادم إنشاء صوت للنص.

  6. يستلم
    response.output_audio.delta

    قم بفك تشفير حقل دلتا Base64 وجمع بايتات PCM بالترتيب. هذه القطع ليست ملفات WAV منفصلة.

  7. يستلم
    response.done

    تحقق من اكتمال Response.status، ثم قم بإضافة رأس WAV واحفظ الصوت الذي تم جمعه. الحالات الأخرى هي الفشل.

افحص رسالة session.update
json
{
  "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-mini
Authorizationstringمطلوب

رأس الاتصال: 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.0
session.audio.output.options.volumenumber | nullخياري

ملحق النظام الأساسي في الخيارات: كسب مضاعف، قيمة محايدة 1.0. نطاق البروتوكول هو 0 < حجم الصوت ≥ 10، ولكن يجب أن يدعمه النموذج. يستخدم المحذوف أو الفارغ القيمة المحايدة؛ يتم رفض القيم غير المدعومة.

الافتراضي / المحذوف 1.0
session.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 ↗