api تایپ صوتی فارسی

برای برقراری ارتباط با سرویس تایپ صوتی همزمان (ASR)، احراز هویت در زمان ایجاد اتصال الزامی است. سرویس iotype از دو روش برای احراز هویت پشتیبانی می‌کند:

در این روش، از Access Token دائمی یا با اعتبار طولانی‌تر برای ایجاد اتصال استفاده می‌شود. این روش برای ارتباطات سمت سرور (Server-to-Server) یا محیط‌هایی که امکان نگهداری امن توکن وجود دارد، مناسب است. پس از اعتبارسنجی موفق Access Token، اتصال WSS برقرار شده و کلاینت می‌تواند جریان صوتی را ارسال و پاسخ‌های تشخیص گفتار را به‌صورت همزمان دریافت کند.

Flash Token یک توکن موقت و کوتاه‌عمر است که برای برقراری یک اتصال ASR صادر می‌شود. این روش به‌ویژه برای برنامه‌های سمت کاربر (Client-side) مانند مرورگرها، اپلیکیشن‌های موبایل و نرم‌افزارهای دسکتاپ توصیه می‌شود؛ زیرا از قرار گرفتن Access Token اصلی در اختیار کاربر جلوگیری می‌کند. فرآیند استفاده از Flash Token به‌صورت زیر است: برنامه سمت سرور با استفاده از Access Token معتبر، یک Flash Token از API دریافت می‌کند. Flash Token به کلاینت ارسال می‌شود. کلاینت با استفاده از Flash Token اتصال WSS را برقرار می‌کند. پس از اعتبارسنجی، سرویس اجازه ارسال جریان صوتی و دریافت نتایج را صادر می‌کند. Flash Token تنها برای مدت زمان محدودی معتبر بوده و پس از انقضا یا استفاده، قابل استفاده مجدد نیست. به همین دلیل، در صورت افشای این توکن، ریسک امنیتی آن نسبت به Access Token بسیار کمتر خواهد بود.

سرویس ASR (Automatic Speech Recognition) امکان تبدیل گفتار به متن را به‌صورت بلادرنگ (Real-Time) فراهم می‌کند. در این سرویس، کلاینت از طریق یک اتصال WebSocket Secure (WSS) به سرورهای iotype متصل شده و هم‌زمان با ارسال جریان صوتی، نتایج تشخیص گفتار را نیز دریافت می‌کند. این معماری باعث می‌شود نیازی به انتظار برای پایان مکالمه نباشد و متن به‌صورت لحظه‌ای در اختیار برنامه قرار گیرد.

آدرس اتصال

برای استفاده از سرویس ASR، اتصال WebSocket را به آدرس زیر برقرار نمایید:

wss://iotype.com/socket/realtime

پس از برقراری موفق اتصال، اولین پیام ارسالی باید شامل اطلاعات احراز هویت و مدل تشخیص گفتار باشد. تا قبل از ارسال این پیام، هیچ داده صوتی نباید برای سرور ارسال شود.

پیام اولیه (Initialize Session)

اولین پیام پس از برقراری اتصال، یک پیام JSON با ساختار زیر است:

{
  "config": {
    "model": "io-fa",
    "type": "flash_token",
    "token": "YOUR_TOKEN"
  }
}

پارامترها

نام	نوع	الزامی	توضیح
model	String	بله	مدل تشخیص گفتار مورد استفاده. مقادیر مجاز: io-fa برای زبان فارسی، io-en برای زبان انگلیسی و io-ar برای زبان عربی
type	String	بله	نوع توکن احراز هویت. مقادیر مجاز: access_token یا flash_token
token	String	بله	مقدار Access Token یا Flash Token جهت احراز هویت اتصال

نکته: تمامی پارامترهای model، type و token باید در شیء config ارسال شوند. تا قبل از ارسال موفق این پیام، هیچ داده صوتی نباید برای سرور ارسال شود.

model

پارامتر model مشخص می‌کند که سرویس از کدام مدل تشخیص گفتار برای پردازش صوت استفاده کند.

مقادیر قابل قبول:

• io-fa : مدل تشخیص گفتار زبان فارسی
• io-en : مدل تشخیص گفتار زبان انگلیسی
• io-ar : مدل تشخیص گفتار زبان عربی

انتخاب مدل صحیح بر اساس زبان گفتار باعث افزایش دقت تشخیص و بهبود کیفیت خروجی خواهد شد.

type

پارامتر type مشخص می‌کند که توکن ارسال‌شده برای احراز هویت از چه نوعی است.

مقادیر قابل قبول:

• access_token
• flash_token

استفاده از Flash Token برای تمامی برنامه‌های سمت کاربر (Browser، Android، iOS، Desktop و ...) توصیه می‌شود.

در برنامه‌هایی که امکان نگهداری امن کلید دسترسی وجود دارد، مانند ارتباطات سمت سرور (Server-to-Server)، می‌توان از Access Token استفاده نمود.

فرمت صوت ارسالی

سرویس ASR داده‌های صوتی را به‌صورت Binary Frame از طریق WebSocket دریافت می‌کند.

ویژگی‌های صوت ورودی

ویژگی	مقدار
Encoding	PCM Linear 16-bit
Channels	Mono
Endian	Little Endian

برای بیشترین دقت تشخیص گفتار، استفاده از صوت با نرخ نمونه‌برداری 16000Hz توصیه می‌شود.

نرخ نمونه‌برداری صوت ورودی باید با داده واقعی ارسال‌شده کاملاً یکسان باشد، در غیر این صورت کیفیت تشخیص کاهش خواهد یافت. همچنین استفاده از صوت تک‌کاناله (Mono) باعث بهبود عملکرد سیستم تشخیص گفتار خواهد شد.

ارسال داده صوتی

پس از ارسال موفق پیام اولیه و تأیید اعتبار اتصال توسط سرور، کلاینت می‌تواند جریان صوتی را ارسال نماید.

داده‌های صوتی باید به‌صورت Binary Message ارسال شوند.

نکات مهم

• داده‌ها نباید به Base64 تبدیل شوند.
• هر پیام WebSocket باید شامل داده خام صوتی باشد.
• ارسال داده‌ها باید مطابق جریان واقعی ضبط صدا انجام شود.
• از ارسال حجم بسیار زیاد داده در یک پیام خودداری نمایید.
• ارسال پیوسته و با حجم‌های کوچک باعث کاهش تأخیر و افزایش کیفیت تشخیص خواهد شد.

پاسخ‌های دریافتی از سرور

در طول فرآیند تشخیص گفتار، سرور پیام‌های JSON را از طریق همان اتصال WebSocket ارسال می‌کند.

پاسخ‌ها در دو دسته اصلی قرار می‌گیرند:

• Partial Result
• Final Result

Partial Result

نتایج Partial متن موقتی هستند که در هنگام صحبت کاربر تولید می‌شوند و ممکن است در پیام‌های بعدی تغییر کنند.

نمونه پاسخ:

{
  "type": "partial",
  "text": "سلام حال"
}

خصوصیات

• ممکن است چندین بار برای یک بخش از گفتار ارسال شود.
• متن آن نهایی نیست.
• در پیام‌های بعدی ممکن است اصلاح یا کامل‌تر شود.
• برای نمایش لحظه‌ای متن در رابط کاربری استفاده می‌شود.

Final Result

پس از پایان یک عبارت یا تشخیص مکث در گفتار، نتیجه نهایی ارسال می‌شود.

نمونه:

{
  "type": "final",
  "text": "سلام حال شما چطور است؟"
}

خصوصیات

• متن نهایی تشخیص داده‌شده است.
• پس از دریافت، مقدار آن تغییر نخواهد کرد.
• می‌تواند در خروجی برنامه ذخیره یا پردازش شود.
• پس از دریافت Final، سیستم آماده پردازش ادامه گفتار خواهد بود.

چرخه کامل ارتباط

فرآیند ارتباط بین کلاینت و سرور به ترتیب زیر انجام می‌شود:

1. برقراری اتصال به wss://iotype.com/socket/realtime
2. ارسال پیام اولیه شامل config.model، config.type و config.token
3. اعتبارسنجی اطلاعات احراز هویت توسط سرور
4. انتخاب مدل تشخیص گفتار بر اساس مقدار config.model
5. شروع ارسال داده‌های صوتی به‌صورت Binary
6. دریافت نتایج Partial در حین صحبت
7. دریافت نتیجه Final پس از پایان هر عبارت
8. ادامه ارسال صوت تا پایان جلسه
9. بستن اتصال WebSocket توسط کلاینت یا سرور

این ساختار امکان تشخیص گفتار با کمترین تأخیر را فراهم می‌کند و برای کاربردهایی مانند دستیارهای صوتی، زیرنویس زنده، دیکته، مراکز تماس و سامانه‌های مکالمه هوشمند مناسب است.