تبدیل گفتار به متن
صدا را از طریق اتصال WebSocket ارسال کنید و بهروزرسانیهای رونویسی را دریافت کنید. این مثال اول یک ضبط را می خواند تا بتوانید بدون تنظیم میکروفون جریان را یاد بگیرید.
wss://api.starsg.ai/v1/realtime?model=asr-altair-v1-miniدر APIهای گفتاری جدید هستید؟ با این چهار اصطلاح شروع کنید.
- WebSocket
- اتصالی که باز می ماند تا برنامه شما و سرور بتوانند در هر دو جهت پیام ها را مبادله کنند.
- مدل
- موتوری که وظیفه را انجام می دهد. از مدل tts برای صحبت کردن و مدل 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 بر ثانیه گفتار. همچنین می توانید از output.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.appendBase64 PCM را در قسمت صوتی ارسال کنید. این مثال از تکههای بایتی 4,800، معادل 100 ms در قالب پیکربندی شده استفاده میکند.
- ارسال کنید
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اختیاریمثال به صراحت null را برای غیرفعال کردن تشخیص چرخش خودکار (VAD) تنظیم می کند. زمانی که تمام صدای ورودی ارسال شد، input_audio_buffer.commit را ارسال کنید. این یک تنظیم انتخاب شده است، نه ادعایی در مورد پیش فرض سرور.
مثال / تنظیمnullaudiostringمورد نیازبایت PCM خام Base64-encoded در input_audio_buffer.append. حداقل 100 ms را در یک نوبت متعهد ارسال کنید. 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 ممکن است از اپراتور خدمات بخواهد در دسترس بودن را بررسی کند.
بدون رونوشت یا خطای فرمت صوتی
از PCM تک، 24 کیلوهرتز، امضا شده 16 بیت کمی با حداقل گفتار 100 میلیثانیه استفاده کنید. Python PCM WAV را می خواند. Node.js PCM را بدون هدر می خواند. ضبط را با استفاده از دستور بالا به جای تغییر نام پسوند آن، تبدیل کنید.
مهلت زمانی یا اتصال قبل از تکمیل بسته می شود
نمونه ها پس از 90 ثانیه متوقف می شوند. ورودی کوتاهتری را امتحان کنید و دسترسی به شبکه را بررسی کنید. رونوشت جزئی یا صوتی جزئی را موفقیت تلقی نکنید. برای جلوگیری از تماس های تکراری، بررسی کنید که آیا درخواست قبلی قبل از تلاش مجدد اجرا شده است یا خیر.
input.wav یا input.pcm پیدا نمی شود
ضبط را در کنار مثال نگه دارید و دستور را از آن پوشه اجرا کنید. Python از input.wav استفاده می کند. Node.js از input.pcm استفاده می کند. متن نهایی بعد از "Final:" ظاهر می شود. تشخیص فایل صوتی ایجاد نمی کند.
پس زمینه پروتکل: OpenAI WebSockets ↗