تحويل الكلام إلى نص
أرسل الصوت عبر اتصال WebSocket واحصل على تحديثات النسخ. يقرأ هذا المثال الأول تسجيلاً حتى تتمكن من معرفة التدفق دون إعداد ميكروفون.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniهل أنت جديد في واجهات برمجة تطبيقات الكلام؟ ابدأ بهذه المصطلحات الأربعة.
- WebSocket
- اتصال يظل مفتوحًا حتى يتمكن البرنامج والخادم من تبادل الرسائل في كلا الاتجاهين.
- نموذج
- المحرك الذي يقوم بالمهمة. استخدم نموذج تحويل النص إلى كلام للتحدث ونموذج ASR للنسخ؛ انسخ المعرف العام الدقيق الخاص به.
- إدخال الصوت
- التسجيل للنسخ. يستخدم هذا المثال أحادي، 24 كيلو هرتز، 16 PCM بت. يقرأ Python الصوت من ملف WAV؛ يقرأ Node.js ملف PCM بدون رأس.
- مفتاح 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 الدائم في صفحة ويب أو مستودع عام. يؤدي تشغيل المثال إلى إجراء استدعاء نموذج قابل للفوترة.
قم بإعداد تسجيل قصير
ضع input.wav في نفس المجلد: mono، 24,000 هرتز، 16 بت PCM WAV، على الأقل 100 مللي ثانية من الكلام. يمكنك أيضًا استخدام input.wav من المثال التجميعي وإعادة تسميته input.wav.
إذا كان تسجيلك يستخدم تنسيقًا آخر، فقم بتثبيت FFmpeg، واستبدل recording.mp3 باسم الملف الخاص بك، ثم قم بتحويله: FFmpeg ↗
ffmpeg -n -i recording.mp3 -ar 24000 -ac 1 -c:a pcm_s16le input.wav
احفظ المثال وقم بتشغيله
انسخ المثال الكامل أدناه إلى ملف نص عادي جديد يسمى speech.py في هذا المجلد. احفظه، ثم قم بتشغيل هذا الأمر في نفس المحطة.
.venv/bin/python speech.py
كيف يبدو النجاحقد يقوم الجهاز بطباعة تحديثات "جزئية:" ثم "نهائية:" متبوعة بالنسخ الكامل. قد تنتج بعض النماذج النتيجة النهائية فقط.
مثال كامل
انسخ الملف بأكمله. يقوم بالاتصال وتكوين الجلسة وإرسال إدخال واحد وانتظار الانتهاء وإغلاق الاتصال. ولا يقوم بإعادة المحاولة تلقائيًا.
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 = "asr-altair-v1-mini"
SESSION = json.loads("{\"type\":\"transcription\",\"audio\":{\"input\":{\"format\":{\"type\":\"audio/pcm\",\"rate\":24000},\"transcription\":{\"model\":\"asr-altair-v1-mini\"},\"turn_detection\":null}}}")
with wave.open("input.wav", "rb") as source:
if (source.getnchannels(), source.getsampwidth(),
source.getframerate(), source.getcomptype()) != (1, 2, 24000, "NONE"):
raise ValueError("Expected mono, 24 kHz, 16-bit PCM WAV")
pcm = source.readframes(source.getnframes())
if len(pcm) < 4800:
raise ValueError("Audio must be at least 100 ms")
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")
for offset in range(0, len(pcm), 4800):
await connection.input_audio_buffer.append(
audio=base64.b64encode(pcm[offset:offset + 4800]).decode()
)
await connection.input_audio_buffer.commit()
transcripts = {}
while True:
event = await receive()
kind = event["type"]
item = (event.get("item_id"), event.get("content_index", 0))
if kind == "conversation.item.input_audio_transcription.delta":
mode = event.get("text_mode", "snapshot")
if mode == "snapshot":
transcripts[item] = event["delta"]
elif mode == "append":
transcripts[item] = transcripts.get(item, "") + event["delta"]
else:
raise ValueError("Unknown text_mode: " + str(mode))
print("Partial:", transcripts[item])
elif kind == "conversation.item.input_audio_transcription.completed":
if not event.get("transcript", "").strip():
raise ValueError("Empty final transcript")
print("Final:", event["transcript"])
return
async def run():
await asyncio.wait_for(main(), timeout=90)
asyncio.run(run())
يستخدم المثال معرف النموذج العام. يعتمد التوفر على حسابك وبيئتك؛ اختر نموذجًا يدعم هذه المهمة في الوقت الفعلي. عرض النماذج ↗
تدفق الحدث
كل رسالة هي حدث JSON. إرسال يعني برنامجك → الخادم؛ تلقي يعني الخادم → البرنامج الخاص بك. انتظر session.updated قبل إرسال المدخلات.
- يستلم
session.createdلقد فتح الخادم جلسة. يمكنك الآن إرسال التكوين الخاص به.
- يرسل
session.updateقم بتعيين جلسة النسخ وتنسيق الصوت المدخل ونموذج التعرف واكتشاف الانعطاف.
- يستلم
session.updatedوافق الخادم على التكوين. الآن أرسل المدخلات.
- يرسل
input_audio_buffer.appendأرسل Base64 PCM في مجال الصوت. يستخدم هذا المثال قطع 4,800 بايت، أي ما يعادل 100 مللي ثانية في التنسيق الذي تم تكوينه.
- يرسل
input_audio_buffer.commitقم بإنهاء دورة الإدخال. مع turn_detection=null، يجب عليك الالتزام بشكل صريح؛ لا ترسل استجابة.إنشاء للتعرف عليها.
- يستلم
conversation.item.input_audio_transcription.deltaقراءة دلتا وtext_mode؛ قم بتحديث item_id وcontent_index المطابقين.
- يستلم
conversation.item.input_audio_transcription.completedحقل النص هو النص النهائي الرسمي. احفظه، ثم أغلق هذا المثال المنعطف الواحد.
افحص رسالة session.update
{
"type": "session.update",
"session": {
"type": "transcription",
"audio": {
"input": {
"format": {
"type": "audio/pcm",
"rate": 24000
},
"transcription": {
"model": "asr-altair-v1-mini"
},
"turn_detection": null
}
}
}
}مرجع المعلمة
تُظهر الأسماء ذات النقاط المكان الذي ينتمي إليه الحقل في كائن JSON. تنطبق كلمة "مطلوب" أدناه على سير العمل في هذا الدليل. يعتمد الدعم والحدود المتقدمة على الطراز.
الاتصال والمصادقة
modelstringمطلوبمعلمة الاستعلام المطلوبة في WebSocket URL. استخدم معرف النموذج العام الدقيق من كتالوج الوقت الفعلي. طرازات ASR وTTS غير قابلة للتبديل.
مثال / الإعدادasr-altair-v1-miniAuthorizationstringمطلوبرأس الاتصال: Bearer، مسافة واحدة، ثم مفتاح API. استخدم المفتاح للبيئة المستهدفة؛ لا تضعه في URL.
مثال / الإعدادBearer <API_KEY>
الجلسة والمدخلات
session.typestringمطلوباستخدم النسخ للتعرف فقط. يقوم بإرجاع النص دون إنشاء رد صوتي مساعد.
مثال / الإعداد"transcription"session.audio.input.formatobjectمطلوبتكوين الصوت: النوع هو الصوت/pcm، والمعدل هو 24000. يستخدم هذا المثال عينات 16 ذات النهاية الصغيرة ذات التوقيع الأحادي: 48,000 بايت في الثانية. لا يتم إرسال رؤوس WAV عبر المقبس.
مثال / الإعداد{"type":"audio/pcm","rate":24000}session.audio.input.transcription.modelstringمطلوباستخدم نفس معرف النموذج العام ASR كاستعلام URL. لا تستبدل اسم طراز البائع الأولي.
مثال / الإعدادasr-altair-v1-minisession.audio.input.turn_detectionobject | nullخيارييقوم المثال بشكل صريح بتعيين قيمة فارغة لتعطيل اكتشاف الانعطاف التلقائي (VAD). أرسل input_audio_buffer.commit عندما يتم إرسال كافة إدخالات الصوت. هذا هو الإعداد المختار، وليس مطالبة بشأن الخادم الافتراضي.
مثال / الإعدادnullaudiostringمطلوبBase64-encoded بايتات PCM الخام في input_audio_buffer.append. أرسل على الأقل 100 مللي ثانية في دور ملتزم. لا يمكن لرأس MP3 أو WAV أو اسم الملف أو URL استبدال هذا الحقل.
استكشاف الأخطاء وإصلاحها
اقرأ الخطأ الذي تم إرجاعه أولاً. لا يعني الاتصال المفتوح أو النص الجزئي أن دورة التعرف هذه قد اكتملت. انتظر النص النهائي.
لم يتم العثور على الأمر أو الوحدة النمطية مفقودة
قم بتثبيت وقت التشغيل المحدد، وأعد فتح الجهاز الطرفي الخاص بك وقم بتشغيل أوامر الإعداد في مجلد المشروع. بالنسبة إلى 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 مللي ثانية من الكلام. Python يقرأ PCM WAV؛ Node.js يقرأ PCM بدون رأس. قم بتحويل التسجيل باستخدام الأمر أعلاه بدلاً من مجرد إعادة تسمية امتداده.
انتهت المهلة أو إغلاق الاتصال قبل الانتهاء
تتوقف الأمثلة بعد ثواني 90. حاول إدخال أقصر وتحقق من الوصول إلى الشبكة. لا تعامل النص الجزئي أو الصوت الجزئي على أنه نجاح. تحقق مما إذا كان الطلب السابق قد تم تشغيله قبل إعادة المحاولة لتجنب المكالمات المتكررة.
لا يمكن العثور على input.wav أو input.pcm
احتفظ بالتسجيل بجانب المثال وقم بتشغيل الأمر من هذا المجلد. يستخدم Python ملف input.wav؛ يستخدم Node.js ملف input.pcm. يظهر النص النهائي بعد "النهائي:"؛ لا يؤدي التعرف إلى إنشاء ملف صوتي.
خلفية البروتوكول: OpenAI WebSockets ↗