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

با استفاده از API تایپ صوتی همزمان (ASR)، می‌توانید گفتار را به‌صورت لحظه‌ای به متن تبدیل کنید. در این سرویس، جریان صوتی از طریق پروتکل WSS (WebSocket Secure) و به‌صورت بسته‌های متوالی (Streaming) به سرورهای iotype ارسال می‌شود. هم‌زمان با دریافت داده‌های صوتی، عملیات تشخیص گفتار انجام شده و نتیجه نیز از طریق همان اتصال WSS به‌صورت آنی برای کلاینت ارسال می‌شود. این سرویس برای کاربردهای بلادرنگ مانند دستیارهای صوتی، زیرنویس زنده، مراکز تماس، سیستم‌های دیکته، و هر سناریویی که نیاز به تبدیل همزمان گفتار به متن دارد، طراحی شده است. با حفظ یک اتصال پایدار WebSocket، می‌توانید بدون انتظار برای پایان مکالمه، متن تشخیص‌داده‌شده را به‌صورت پیوسته دریافت و در برنامه خود نمایش یا پردازش کنید.

این متن برای دستیارهای هوش مصنوعی است.

Realtime Persian ASR over WebSocket — wss://iotype.com/socket/realtime

This is the only iotype service that accepts a Flash Token. Every other service authenticates with an Access Token over HTTP.

The protocol has four steps. Skipping any of them breaks the session.

1 — Handshake. The first message on the socket, sent as a text frame. The three fields are nested inside a config envelope:

{"config":{"model":"io-fa","type":"access_token","token":"<TOKEN>"}}

config.type is access_token (server-side) or flash_token (browser, mobile, desktop). config.model is io-fa, io-en or io-ar.

2 — Wait for the authorization reply. The server responds:

{"status":"authorized","sample_rate":16000,"model":"io-fa"}

3 — Stream audio as WebSocket binary frames: raw PCM, signed 16-bit, little-endian, mono, at the negotiated sample rate. One frame per 20 ms, so frame_size = sample_rate / 50 samples (sample_rate / 25 bytes).

4 — Terminate. Send the text frame {"eof":1}, wait a few seconds for the trailing result, then close.

Results arrive as text frames under two different keys — there is no type field, so discriminate on key presence:

Message	Meaning
`{"partial":"..."}`	interim hypothesis; may be revised — render, do not persist
`{"text":"..."}`	settled for that utterance — persist this one

A session emits many text messages, one per utterance.

Machine-readable documentation:

Full guide: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/docs/en/realtime-asr.md
AsyncAPI 3.0 specification: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/spec/asyncapi.yaml
Authentication and the Flash Token flow: https://raw.githubusercontent.com/iotype-ai/iotype-api/main/docs/en/authentication.md
Tested browser client: https://github.com/iotype-ai/iotype-api/tree/main/examples/browser-asr
Repository: https://github.com/iotype-ai/iotype-api

Official SDKs: pip install "iotype-ai[realtime]" · composer require iotype-ai/sdk · npm i @iotype-ai/sdk · go get github.com/iotype-ai/iotype-api/sdk/go

Implementation notes that are commonly got wrong:

sample_rate is negotiated, not constant. Read it from the authorization reply and resample to exactly that rate. Do not hard-code 16000 — it is a deployment detail and it can change.
Do not send audio before the authorization reply arrives. The server closes the connection.
Do not base64-encode the audio. Frames must be raw binary. Sending a text frame of base64 fails silently — the session stays open and produces nothing.
Without {"eof":1} the final utterance is lost. Do not close the socket immediately after sending it either; the last result arrives shortly after.
Do not persist partial messages. Replace the interim display on each one and append only on text. Concatenating partials duplicates text.
On reconnect, mint a fresh Flash Token — they are single-use.

Get a token: https://iotype.com/api-service/authentication

احراز هویت اتصال به وب سرویس Realtime Transcription

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

استفاده از Access Token

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

استفاده از Flash Token

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

توصیه امنیتی

در برنامه‌های سمت کاربر هرگز Access Token را به‌صورت مستقیم در کد یا درخواست‌های WebSocket قرار ندهید. همواره از Flash Token استفاده کنید و Access Token را تنها در سرور خود نگهداری نمایید.

PHP

JAVASCRIPT

PYTHON

نمونه کد دریافت Flash Token

<?php
$url = "https://iotype.com/io/v1/flash-token";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TOKEN",
        "Accept: application/json",
        "X-Requested-With: XMLHttpRequest"
    ],
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

پارامترهای ارسالی در Header درخواست دریافت Flash Token

Authorization

Bearer [TOKEN]

application/json

X-Requested-With

XMLHttpRequest

نحوه برقراری ارتباط با سرویس تایپ صوتی همزمان (ASR)

سرویس 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، سیستم آماده پردازش ادامه گفتار خواهد بود.

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

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

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

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

نمونه کد استریم از میکروفون به سرور

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