راهنمای اتصال

نمونه کدهای اتصال

وب‌سرویس ابری آریانا مبتنی بر استاندارد REST و بر پایه پروتکل HTTP طراحی شده است.

برای استفاده از سرویس ابری آریانا نیاز به دریافت کد کاربری (APIKey) دارید. برای این می‌توانید به وبسایت عصر گویش پرداز مراجعه نموده و پس از ثبت نام در سایت، از آدرس http://asr-gooyesh.com/fa/arianacloud-dashboard کد کاربری خود را دریافت نمایید و از شارژ رایگان اولیه استفاده نمایند.

نصب و راه اندازی

متد GET

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey={KEY}&Text={TEXT}&Speaker={SPEAKER}&Format={FORMAT}&GainLevel={GAIN}&PitchLevel={PITCH}&PunctuationLevel={PUNCTUATION}&SpeechSpeedLevel={SPEED}&ToneLevel={TONE}&Quality={QUALITY}&BeginningSilence={SEC}&EndingSilence={SEC}&Base64Encode={TYPE}

مثال:

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey=XYZ&Text=hello&Speaker=Female1&Format=mp3&GainLevel=0&PitchLevel=0&PunctuationLevel=0&SpeechSpeedLevel=0&ToneLevel=0 uality=normal&BeginningSilence=0&EndingSilence=0&Base64Encode=0

یا به طور خلاصه:

http://api.farsireader.com/ArianaCloudService/ReadTextGET?APIKey=XYZ&Text=hello&Speaker=Female1&Format=mp3

در متد GET پارامترهای Text و Format باید به فرمت URL Encoded تبدیل شوند. برای مثال، عبارت “تست” به صورت “%D8%AA%D8%B3%D8%AA” ارسال می‌شود.

همچنین توجه شود که در این متد، با رسیدن هر درخواست به سرور، شارژ حساب کاربری به تعداد مجموع کلمات (هر پیام معادل حداکثر 25 کلمه) کسر خواهد شد. در بعضی مرورگرها و یا ابزارهای دانلود، رایج است که برای تسریع بارگذاری فایل، درخواست‌های (Connection) مکرر و همزمان به سمت سرور ارسال می‌شود که هر کدام از این درخواست‌ها باعث کسر شارژ از حساب کاربری خواهد شد. بنابراین توصیه می‌شود فایل صوتی حاصل از متد GET را فقط با یک Connection دانلود نمایید.

متد POST

http://api.farsireader.com/ArianaCloudService/ReadText

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

Content-type: application/json

{
“Text”:”متن درخواستی”,
“Speaker”:”Female1″,
“PitchLevel”:”0″,
“PunctuationLevel”:”0″,
“SpeechSpeedLevel”:”0″,
“ToneLevel”:”0″,
“GainLevel”:”0″,
“BeginningSilence”:”0″,
“EndingSilence”:”0″,
“Format”:”mp3″,
“Base64Encode”:”0″,
“Quality”:”normal”,
“APIKey”:”mykey”
}

توجه شود که حتماً در Header درخواست POST، نوع داده (Content-type) به صورت application/json مشخص گردد.

سرویس آریانا پس از پردازش متن درخواستی، صوت تبدیل شده را در جواب به صورت Byte Stream ارسال می‌نماید.
درخواست پردازش متن به صورت غیر هم‌زمان (Blocking) بوده و کلاینت موظف است تا اتمام پردازش متن و آماده شدن کامل صوت، منتظر پاسخ بماند. لذا نیاز است پارامتر Timeout در کلاینت به مقدار مناسبی تنظیم شود تا درخواست POST قبل از اتمام پردازش قطع نشود. مقدار پیشنهادی این پارامتر برای متن طولانی، حداقل 120 ثانیه است.

شرح پارامترها

Text	متن درخواستی برای پردازش
Speaker	گوینده متن مقادیر: Female1, Male2, Male1 (پیش‌فرض Female1) انتخاب پیش‌فرض: ” (empty string)
PitchLevel	میزان زیر و بمی صدا مقادیر: 1 تا 10 (پیش‌فرض 4) انتخاب پیش‌فرض: 0
PunctuationLevel	سطح خواندن علائم نگارشی مقادیر: 1 تا 3 (پیش‌فرض 2) انتخاب پیش‌فرض: 0
SpeechSpeedLevel	سرعت خواندن مقادیر: 1 تا 10 (پیش‌فرض 5) انتخاب پیش‌فرض: 0
ToneLevel	تن صدا مقادیر: 1 تا 19 (پیش‌فرض 10) انتخاب پیش‌فرض: 0
GainLevel	بلندی صدا مقادیر: 1 تا 5 (پیش‌فرض 3) انتخاب پیش‌فرض: 0
BeginningSilence	تعداد ثانیه های سکوت ابتدای صوت مقادیر: 0 تا 5 (پیش‌فرض 0)
EndingSilence	تعداد ثانیه های سکوت انتهای صوت مقادیر: 0 تا 5 (پیش‌فرض 0)
Format	مقادیر فرمت گفتار تبدیل شده: wav16: Wave 16KHz Mono 16bit alaw16: Wave 16KHz Mono a-law 8bit mlaw16: Wave 16KHz Mono mu-law 8bit wav8: Wave 8KHz Mono 16bit alaw8: Wave 8KHz Mono a-law 8bit mlaw8: Wave 8KHz Mono mu-law 8bit mp3: MP3 32Kbps Mono ogg: OGG (Opus) 32Kbps Mono raw16: Raw Wave 16KHz Mono 16bit, Without 44 Bytes Wave Header (پیش‌فرض wav16) انتخاب پیش‌فرض: ” (empty string)
Quality	کیفیت صدای ساخته شده مقادیر: normal: صدا با کیفیت نرمال – پیش فرض low: صدا با کیفیت کم‌تر و زمان ساخت سریع‌تر
Base64Encode	استفاده از Base64 Encoding در ارسال متن ورودی و بافر صوتی خروجی مقادیر: 0 تا 4 (پیش‌فرض 0) مقادیر 0 و 1 از Base64 Encoding استفاده نمی‌شود. مقدار 2 برای ارسال متن ورودی از Base64 Encoding استفاده شده است. مقدار 3 برای ارسال بافر صوتی خروجی از Base64 Encoding استفاده می‌شود. مقدار 4 برای ارسال متن ورودی و بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
APIKey	کد کاربری استفاده از سرویس ابری آریانا که در پنل کاربری در سایت قابل دسترسی است.

انتخاب پیش‌فرض، مقداری را انتخاب می‌کند که در آریانا کنسول در قسمت Speech/Text Defaults تعیین شده است.

اتصال به سرویس REST آریانا

وب‌سرویس آریانا مبتنی بر استاندارد REST و بر پایه پروتکل HTTP طراحی شده است. دسترسی به این سرویس از طریق متد تشریح شده در ذیل ممکن است. برنامه‌های نمونه شامل تمام قابلیت‌های موجود در سرویس آریانا به همراه سورس‌کد مربوطه در پوشه نصب آریانا قابل دسترس هستند.

آدرس متد

http://{ServerIP}:{ServerPort}/ArianaRESTService/ReadText/

مقدار پیش فرض Server Port تنظیم شده در کنسول آریانا، 1385 است.

ساختارهای فراخوانی

فراخوانی متد توسط HTTP POST انجام می‌شود.
فرمت ورود داده‌ها بدین شکل است:

Content-type: application/json

{
“Text”:”متن درخواستی”,
“Speaker”:”Female1″,
“PitchLevel”:”0″,
“PunctuationLevel”:”0″,
“SpeechSpeedLevel“:”0“,
“ToneLevel”:”0“,
“GainLevel”:”0“,
“BeginningSilence”:”0“,
“EndingSilence”:”0“,
“Format”:”mp3″,
“Quality”:”normal”,
“Base64Encode“:”0”,
“Username”:”test”,
“Password”:”test”
}

توجه شود که حتماً در Header درخواست POST، نوع داده (Content-type) به صورت application/json مشخص گردد.

شرح پارامترها

Text	متن درخواستی برای پردازش
Speaker	گوینده متن مقادیر: Female1, Male1 (پیش‌فرض Female1) انتخاب پیش‌فرض: ” (empty string)
PitchLevel	میزان زیر و بمی صدا مقادیر: 1 تا 10 (پیش‌فرض 4) انتخاب پیش‌فرض: 0
PunctuationLevel	سطح خواندن علائم نگارشی مقادیر: 1 تا 3 (پیش‌فرض 2) انتخاب پیش‌فرض: 0
SpeechSpeedLevel	سرعت خواندن مقادیر: 1 تا 10 (پیش‌فرض 5) انتخاب پیش‌فرض: 0
ToneLevel	تن صدا مقادیر: 1 تا 19 (پیش‌فرض 10) انتخاب پیش‌فرض: 0
GainLevel	بلندی مقادیر: 1 تا 5 (پیش‌فرض 3) انتخاب پیش‌فرض: 0
BeginningSilence	تعداد ثانیه های سکوت ابتدای صوت مقادیر: 0 تا 5 (پیش‌فرض 0)
EndingSilence	تعداد ثانیه های سکوت انتهای صوت مقادیر: 0 تا 5 (پیش‌فرض 0)
Format	فرمت گفتار تبدیل شده مقادیر: wav16: Wave 16KHz Mono 16bit alaw16: Wave 16KHz Mono a-law 8bit mlaw16: Wave 16KHz Mono mu-law 8bit wav8: Wave 8KHz Mono 16bit alaw8: Wave 8KHz Mono a-law 8bit mlaw8: Wave 8KHz Mono mu-law 8bit mp3: MP3 32Kbps Mono ogg: OGG (Opus) 32Kbps Mono raw16: Raw Wave 16KHz Mono 16bit, Without 44 Bytes Wave Header (پیش‌فرض wav16) انتخاب پیش‌فرض: ” (empty string)
Quality	کیفیت صدای ساخته شده مقادیر: normal: صدا با کیفیت نرمال – پیش فرض low: صدا با کیفیت کم‌تر و زمان ساخت سریع‌تر
Base64Encode	استفاده از Base64 Encoding در ارسال متن ورودی و بافر صوتی خروجی مقادیر: 0 تا 4 (پیش‌فرض 0) مقادیر 0 و 1 از Base64 Encoding استفاده نمی‌شود. مقدار 2 برای ارسال متن ورودی از Base64 Encoding استفاده شده است. مقدار 3 برای ارسال بافر صوتی خروجی از Base64 Encoding استفاده می‌شود. مقدار 4 برای ارسال متن ورودی و بافر صوتی خروجی از Base64 Encoding استفاده می‌شود.
Username/ Password	نام کاربری و گذرواژه تعریف شده در تنظیمات آریانا کنسول

انتخاب پیش‌فرض، مقداری را انتخاب می‌کند که در آریانا کنسول در قسمت Speech/Text Defaults تعیین شده است.