متن را به گفتار تبدیل کنید
متن را از طریق اتصال WebSocket ارسال کنید و صدا را به صورت تکه تکه دریافت کنید. با یک مثال کامل شروع کنید که یک فایل WAV قابل پخش را ذخیره می کند.
wss://api.starsg.ai/v1/realtime?model=tts-altair-v1-miniدر APIهای گفتاری جدید هستید؟ با این چهار اصطلاح شروع کنید.
- WebSocket
- اتصالی که باز می ماند تا برنامه شما و سرور بتوانند در هر دو جهت پیام ها را مبادله کنند.
- مدل
- موتوری که وظیفه را انجام می دهد. از مدل tts برای صحبت کردن و مدل 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
موفقیت چه چیزی به نظر می رسدترمینال "Saved:" را چاپ می کند و output.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 را در ترمینال خود تنظیم کنید. برای استفاده از صدای پیش فرض آن را حذف کنید. نام نمایشی مانند "آلیاژ" 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بررسی کنید answer.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مورد نیازمتن برای ترکیب، در داخل talk.item.create → item → content. نوع مورد محتوا را روی 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 کیلوهرتز، مونو، 16 بیت کمی PCM و حداقل 100 بر میلیثانیه گفتار را بررسی کنید. به جای تغییر نام فایل از دستور تبدیل استفاده کنید. تشخیص، PCM خام را ارسال می کند، نه هدر WAV. برای سنتز، Base64 را رمزگشایی کنید و قبل از ایجاد یک فایل WAV به قطعات PCM بپیوندید.
invalid_value یا یک کنترل پشتیبانی نشده
تنظیمات اختیاری سرعت، صدا و گام را حذف کنید، سپس output_controls را برای مدل انتخابی بررسی کنید. از voice_id یا محدودیت های عددی مدل دیگر استفاده مجدد نکنید. یک session.update رد شده آن پیکربندی را اعمال نمی کند.
مهلت زمانی یا اتصال قبل از تکمیل بسته می شود
نمونه ها پس از 90 ثانیه متوقف می شوند. ورودی کوتاهتری را امتحان کنید و دسترسی به شبکه را بررسی کنید. رونوشت جزئی یا صوتی جزئی را موفقیت تلقی نکنید. برای جلوگیری از تماس های تکراری، بررسی کنید که آیا درخواست قبلی قبل از تلاش مجدد اجرا شده است یا خیر.
output.wav از قبل وجود دارد یا فایل ورودی وجود ندارد
اسکریپت را از پوشه حاوی speech.py یا speech.mjs اجرا کنید. input.wav (Python) یا input.pcm (Node.js) را در آنجا قرار دهید. قبل از ایجاد مجدد نام output.wav قبلی را تغییر دهید. خط "نهایی:" نتیجه تشخیص است. فایل صوتی ایجاد نمی کند.
پس زمینه پروتکل: OpenAI WebSockets ↗